> ## Documentation Index
> Fetch the complete documentation index at: https://hmis-docs.derrickmugabwa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create the Dokploy project

> Connect the HMIS repository and configure its production Docker Compose service.

Create separate Dokploy projects or environments for staging and production. Each must use unique domains, secrets, databases, volumes, integration identities, and tokens.

<Steps>
  <Step title="Create the project and environment">
    In Dokploy, create an HMIS project and a `staging` or `production` environment. Assign access only to the operators responsible for that environment.
  </Step>

  <Step title="Create a Docker Compose service">
    Select a Git source, connect the HMIS repository, and choose the approved branch. Use:

    ```text theme={null}
    Compose path: docker-compose.yml
    Build context: repository root
    ```

    Do not select `docker-compose.local.yml`; it publishes development endpoints and mounts source files intended for Docker Desktop.
  </Step>

  <Step title="Configure deployment behavior">
    Disable automatic production deployment until the staging and approval workflow is established. Keep `RUN_MIGRATIONS=false`; migrations must run exactly once as a controlled release step.
  </Step>

  <Step title="Add environment variables">
    Enter the variables from [Production environment variables](/platform/deployment/environment-variables). Do not upload the application's local `.env` file.
  </Step>

  <Step title="Render and review Compose">
    Confirm that the project resolves these services before the first deployment:

    ```text theme={null}
    app, queue, scheduler, postgres,
    oie, oie-postgres,
    orthanc, orthanc-postgres, ohif,
    mock-analyzer, mock-modality
    ```
  </Step>

  <Step title="Save without clinical traffic">
    Do not point production user or device traffic at the service until domains, storage, migrations, administrator setup, backups, and smoke tests are complete.
  </Step>
</Steps>

## Repository access

* Use a dedicated read-only deploy key or Git application when possible.
* Protect the production branch and require review and passing tests.
* Pin the commit used for each release record.
* Revoke repository access when a deployment operator leaves the role.

## Current Compose limitation

<Warning>
  The repository does not yet define Compose profiles. A normal Dokploy Compose deployment therefore creates the optional integration services and both mock services, even when they are not needed.
</Warning>

For production:

1. Do not create domains for `mock-analyzer` or `mock-modality`.
2. Stop both mock services immediately after every deployment.
3. Confirm their state is stopped during each go-live and release check.
4. Keep all simulator ports blocked at the host and network firewall.
5. Track a future application-infrastructure change to introduce `core`, `integration`, and `demo` Compose profiles.

Stopping the services is an operational workaround, not a permanent configuration. A full Compose redeployment can start them again.

## Environment parity

Staging should use the same Compose file and image build as production. Differences must be limited to domains, secrets, data, resources, mail behavior, integrations, and simulator access.

Next, configure [environment variables](/platform/deployment/environment-variables) and [domains and storage](/platform/deployment/domains-and-storage).