Skip to main content

Project Standard (Adding a New Service)

This guide defines the engineering standards and protocols for contributing to the infrastructure.

️ The Autonomous Project Protocol​

Any service added to this infrastructure must adhere to the Modular Orchestration Protocol. This ensures that the global orchestrator (run.sh) can discover, configure, and manage the service automatically.

Project Structure Requirements​

A project directory must contain:

  1. project.conf: Metadata for the local orchestrator (priority, persistence, enable/disable).
  2. docker-compose.yml: Container definition (attach to the shared network from DOCKER_NETWORK_NAME).
  3. .env.template (preferred) or .env.example: Variables required by the service.
  4. run.sh: Optional wrapper for service-local commands (the repo uses ./infra.sh as the main entrypoint).

Tutorial: Adding a New Service​

1. Create the Directory​

Place your project in the appropriate category folder (e.g., processing/my-new-app).

2. Connect to the shared network​

Use the shared network from root .env (DOCKER_NETWORK_NAME).

3. Integrate with env generation​

  • Put non-secret defaults in ./<project>/.env.template.
  • Reference global secrets via ${GLOBAL_*} placeholders when needed.
  • ./infra.sh env generate should produce ./<project>/.env without manual edits.

️ Global Tooling for Developers​

  • ./infra.sh env check validates missing keys.
  • ./infra.sh test health runs safe checks.
  • ./infra.sh test infra runs a full destructive validation.