App Design Guidelines

This document is intended for developers who build software with a web interface and want to distribute it through the Ocelot App Store. You are free to design your app in any way you like. However, following the guidelines in this document ensures smooth integration with Ocelot-Cloud and improves the experience for administrators and end users. Apps that adhere closely to these principles are more likely to be featured as official apps in the Ocelot App Store.

Introduction and development model

Any software that provides a web interface can be published as an app in the Ocelot App Store. At a high level, the development and distribution flow looks like this:

  • You package your software as a Docker image and publish it to a public registry.
  • You provide a docker-compose.yml that follows Ocelot-Cloud conventions and upload the app to the Ocelot App Store. See App Creation article.
  • Users can download the app from the App Store and install it in their Ocelot-Clouds.

What Ocelot-Cloud handles for you

Ocelot-Cloud provides a standardized operational environment. App developers should assume that the following concerns are handled externally and do not need to be implemented by the app itself:

  • Reverse proxying and TLS certificate management
  • Network security
  • Update orchestration and restarts
  • Backups and restores
  • Monitoring and alerting
  • User management

Relying on these platform features avoids duplication and prevents interference between app-level and platform-level behavior.

Design recommendations

Installation and updates

  • The app must be deployable using a simple docker compose up without manual pre- or post-installation steps.
  • All services in docker-compose.yml should have meaningful, descriptive names. For example, use ‘database’ instead of ‘db’ or ‘service1’.
  • Apps are frequently started and stopped, which is why these operations should be quick.
  • Installation wizards and web-based configuration are acceptable
  • Updates should be non-interactive.
    • The app should apply database migrations automatically
    • The app should migrate configuration automatically. Users should never be asked to resolve configuration conflicts.

Networking and reverse proxy model

  • Apps should not:
    • Terminate TLS
    • Manage certificates
    • Enforce hard-coded domain checks
    • Require IP allowlists
  • If domain or URL awareness is required, it must be configurable via environment variables. Ocelot-Cloud can dynamically inject values such as the host name on startup.
  • The main service must serve its web interface at /.

Configuration model

Configuration should be handled by the app itself and should not complicate deployment. Preferred configuration order:

  1. Opinionated defaults built into the app. These should cover the common case and remain hidden from administrators where possible.
  2. Environment variables in docker-compose.yml are used for:
    • Static configuration that rarely changes
    • Dynamic configuration injected by Ocelot-Cloud. See section ‘Environment variables’.
  3. Web-based configuration via the app’s UI. Used for settings that may change over time.

Manual configuration via the command line or direct editing of config files is discouraged, as it increases operational complexity. Internally managed config files are acceptable if they are fully controlled by the app.

Environment variables

Apps should be able to read the following environment variables, as Ocelot-Cloud may inject them: HOST, OIDC-related settings and SMTP-related settings (may be empty). See App Creation article. On startup, the app should apply these values automatically. Restarting the app must be sufficient to adapt to configuration changes.

Operations

Efficiency and simplicity

  • Apps should be efficient in terms of CPU, memory, and disk usage. Apps should be able to run on low-end hardware.
  • Docker images should be small. Minimal base images such as Alpine are preferred.
  • Prefer compiled languages that produce static binaries, such as Go or Rust.
  • Minimize the number of services in docker-compose.yml.
    • Apps are deployed on a single node, so designing the software as a horizontally scalable, multi-container architecture is unnecessary
    • Ideally one main service with the HTTP interface
    • A database container if required
    • Additional services (search engines, LLMs, etc.) only if necessary
  • Prefer a single, opinionated deployment approach. If multiple backends are supported (for example databases), choose the most common one instead of creating multiple app variants.

Dependency handling

If the main service depends on other services (for example a database), it should:

  • Attempt to connect on startup
  • Retry for a reasonable amount of time or number of attempts
  • Exit with an error if the dependency is unavailable

Flexibility

Apps should tolerate frequent restarts and operational changes, including:

  • Domain changes
  • User creation, deletion, or renaming
  • Configuration changes

Avoid hard-coded assumptions or irreversible dependencies.

Logging and observability

Apps should be configurable via Docker environment variables to:

  • Log exclusively to stdout and stderr
  • Avoid log files and internal log rotation
  • Use structured logging where possible

Ocelot-Cloud collects logs centrally, so writing logs to the filesystem is unnecessary. JSON is the preferred log format, as it integrates well with centralized logging and monitoring systems. Plain text logging is acceptable but may not be parsed reliably.

User management and security

Apps should support integration with an identity provider via OIDC. This enables seamless integration with Ocelot-Cloud features such as:

  • Single sign-on
  • User and group management
  • Group-based access control

The app remains fully responsible for implementing and enforcing its own authorization logic.

Licensing

  • While open-source software is preferred for official apps, the Ocelot App Store also accepts proprietary software.