Local Development

This article describes how to set up a local development environment for Ocelot-Cloud and some tips and tricks to make the development experience smoother.

For local development, you should run Ocelot-Cloud in TEST mode docker container using the ci-runner tool. This mode is optimized for development and testing, so there are some features implemented which make the development experience smoother. This includes:

  • when running docker container in test mode, you can add the flag -k to keep the database and uploaded files between restarts. This way, you don’t have to login or set up everything from scratch on each change of backend code and subsequent restart.
  • Changing web resource files (HTML, CSS, JS) on the host system can be reloaded from the GUI, so no restart is necessary.
  • a dummy SSH server is started to allow SSH connections and creating backups.
  • test-apps are apps for
  • Usually when working with test apps, you might need a valid TLS certificate for testing integration with Ocelot-Cloud as an OIDC provider.
    • Set the domain in the /etc/hosts file to point to localhost (e.g. ocelotcloud.test.ocelot-cloud.org -> 127.0.0.1), do this also with all expected app domains.
    • Run Ocelot-Cloud in prod mode
    • Set a test domain in the settings that you own (e.g. we usually use test.ocelot-cloud.org)
    • Generate a TLS certificate via DNS-01 challenge
    • Download the generated certificate (certificate.pem)
    • Stop Ocelot-Cloud and restart it in TEST mode
    • Set the host again and upload the previously downloaded certificate
    • Restart your browser and revisit Ocelot-Cloud under ocelotcloud.<test-domain> (for example ocelotcloud.test.ocelot-cloud.org)

For local development, Ocelot-Cloud should usually be run in TEST mode inside a Docker container using the ci-runner tool. TEST mode provides features optimizing development.