Skip to main content

Developing COSMOS

So you want to help develop COSMOS? All of our open source COSMOS code is on Github so the first thing to do is get an account. Next clone the COSMOS repository. We accept contributions from others as Pull Requests.

Development Tools​

The core COSMOS team develops with the Visual Studio Code editor and we highly recommend it. We also utilize a number of extensions including docker, kubernetes, gitlens, prettier, eslint, python, vetur, and ruby. We commit our openc3.code-workspace configuration for VSCode to help configure these plugins. You also need Docker Desktop which you should already have as it is a requirement to run COSMOS. You'll also need NodeJS and yarn installed.

Building COSMOS

Note: We primarily develop COSMOS in MacOS so the commands here will reference bash scripts but the same files exist in Windows as batch scripts.

Build COSMOS using the openc3.sh script:

% ./openc3.sh build

This will pull all the COSMOS container dependencies and build our local containers. Note: This can take a long time especially for your first build!

Once the build completes you can see the built images with the following command:

% docker image ls | grep "openc3" openc3inc/openc3-cosmos-init latest 4cac7a3ea9d3 29 hours ago 446MB openc3inc/openc3-cosmos-script-runner-api latest 4aacbaf49f7a 29 hours ago 431MB openc3inc/openc3-cosmos-cmd-tlm-api latest 9a8806bd4be3 3 days ago 432MB openc3inc/openc3-operator latest 223e98129fe9 3 days ago 405MB openc3inc/openc3-base latest 98df5c0378c2 3 days ago 405MB openc3inc/openc3-redis latest 5a3003a49199 8 days ago 111MB openc3inc/openc3-traefik latest ec13a8d16a2f 8 days ago 104MB openc3inc/openc3-minio latest 787f6e3fc0be 8 days ago 238MB openc3inc/openc3-node latest b3ee86d3620a 8 days ago 372MB openc3inc/openc3-ruby latest aa158bbb9539 8 days ago 326MB

Offline Building

If you're building in a offline environment or want to use a private Rubygems, NPM or APK server (e.g. Nexus), you can update the following environment variables: RUBYGEMS_URL, NPM_URL, APK_URL, and more in the .env file. Example values:

ALPINE_VERSION=3.18
ALPINE_BUILD=5
RUBYGEMS_URL=https://rubygems.org
NPM_URL=https://registry.npmjs.org
APK_URL=http://dl-cdn.alpinelinux.org

Running COSMOS

Running COSMOS in development mode enables localhost access to internal API ports as well as sets RAILS_ENV=development in the cmd-tlm-api and script-runner-api Rails servers. To run in development mode:

% ./openc3.sh dev

You can now see the running containers (I removed CONTAINER ID, CREATED and STATUS to save space):

% docker ps IMAGE COMMAND PORTS NAMES openc3/openc3-cmd-tlm-api:latest "/sbin/tini -- rails…" 127.0.0.1:2901->2901/tcp openc3_openc3-cmd-tlm-api_1 openc3/openc3-script-runner-api:latest "/sbin/tini -- rails…" 127.0.0.1:2902->2902/tcp openc3_openc3-script-runner-api_1 openc3/openc3-traefik:latest "/entrypoint.sh trae…" 0.0.0.0:2900->80/tcp openc3_openc3-traefik_1 openc3/openc3-operator:latest "/sbin/tini -- ruby …" openc3_openc3-operator_1 openc3/openc3-minio:latest "/usr/bin/docker-ent…" 127.0.0.1:9000->9000/tcp openc3_openc3-minio_1 openc3/openc3-redis:latest "docker-entrypoint.s…" 127.0.0.1:6379->6379/tcp openc3_openc3-redis_1

If you go to localhost:2900 you should see COSMOS up and running!

Running a Frontend Application​

So now that you have COSMOS up and running how do you develop an individual COSMOS application?

  1. Bootstrap the frontend with yarn

    openc3-init % yarn

  2. Serve a local COSMOS application (CmdTlmServer, ScriptRunner, etc)

    openc3-init % cd plugins/packages/openc3-tool-scriptrunner openc3-tool-scriptrunner % yarn serve

    DONE Compiled successfully in 128722ms App running at:

    Note that the development build is not optimized. To create a production build, run npm run build.

  3. Set the single SPA override for the application

    Visit localhost:2900 and Right-click 'Inspect'
    In the console paste:

    localStorage.setItem('devtools', true)

    Refresh and you should see {...} in the bottom right
    Click the Default button next to the application (@openc3/tool-scriptrunner)
    Paste in the development path which is dependent on the port returned by the local yarn serve and the tool name (scriptrunner)

    http://localhost:2914/tools/scriptrunner/js/app.js

  4. Refresh the page and you should see your local copy of the application (Script Runner in this example). If you dynamically add code (like console.log) the yarn window should re-compile and the browser should refresh displaying your new code. It is highly recommended to get familiar with your browser's development tools if you plan to do frontend development.

Running a Backend Server​

If the code you want to develop is the cmd-tlm-api or script-runner-api backend servers there are several steps to enable access to a development copy.

  1. Run a development version of traefik. COSMOS uses traefik to direct API requests to the correct locations.

    % cd openc3-traefik traefik % docker ps

    Look for the container with name including traefik

    traefik % docker stop openc3_openc3-traefik_1 traefik % docker build -f Dockerfile-dev -t openc3-traefik-dev . traefik % docker run --network=openc3-cosmos-network -p 2900:80 -it --rm openc3-traefik-dev

  2. Run a local copy of the cmd-tlm-api or script-runner-api

    % cd openc3-cmd-tlm-api openc3-cmd-tlm-api % docker ps

    Look for the container with name including cmd-tlm-api

    openc3-cmd-tlm-api % docker stop openc3_openc3-cmd-tlm-api_1

    Set all the environment variables in the .env file

    openc3-cmd-tlm-api % bundle install openc3-cmd-tlm-api % bundle exec rails s

  3. Once the rails s command returns you should see API requests coming from interations in the frontend code. If you add code (like Ruby debugging statements) to the cmd-tlm-api code you need to stop the server (CTRL-C) and restart it to see the effect.