> ## Documentation Index
> Fetch the complete documentation index at: https://libops-renovate-github-com-libops-sitectl-isle-0-x.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed applications

> How sitectl-managed application templates use Docker Compose, local image builds, and development overrides.

export const Compose = () => <Tooltip headline="Compose" tip={<>
        Docker Compose is Docker's tool for defining and running multi-container applications.{" "}
        <a href="https://docs.docker.com/compose/">https://docs.docker.com/compose/</a>.
      </>}>
    <>
      <Icon icon="docker" />
      {" "}
      Compose
    </>
  </Tooltip>;

`sitectl` application templates are normal <Compose /> projects with a shared operating contract. The repository owns the application workload, and `sitectl` supplies context-aware lifecycle commands, component updates, health checks, image overrides, and service helpers.

## Compose Files

`docker-compose.yml` or `docker-compose.yaml` is the production contract. It should describe the stack that runs on the host: services, volumes, secrets, Traefik ingress, health checks, build definitions, and the default published ports.

Local-only changes belong in `docker-compose.override.yml`. That file is intentionally ignored by template repositories. Developers can use it for temporary bind mounts, image overrides, secrets used only on their workstation, and port swaps. Production should not rely on a Compose override file; production behavior should be visible in the tracked Compose file and tracked component changes.

When an application service requires MariaDB during startup, declare that relationship in the tracked Compose file with `depends_on` and `condition: service_healthy`. The application plugins' standard healthcheck runner verifies that policy for MariaDB-backed web apps.

## Local Image Builds

Every application template includes a Dockerfile for the local application image. The Dockerfile starts from the matching LibOps base image, copies lockfiles and downloaded dependencies before copying local modules, plugins, themes, config, or other customization points, and leaves runtime configuration to the Compose environment where possible.

This keeps local builds fast:

* Docker can reuse package-manager and download cache layers when only local custom code changed.
* The build uses the platform selected by the Docker CLI on the host.
* Local builds do not push images. Publishing images belongs in CI or another explicit release workflow.

The LibOps base images provide the default PHP and nginx configuration. When a template needs to tune upload size, timeouts, trusted proxy handling, or similar runtime behavior, prefer environment values in the Compose service over rebuilding nginx or PHP config into the downstream template image.

Use [`sitectl image set`](/commands/image) when you need a local context to run a different image, tag, or build argument without editing the tracked template files.

## Development Ports

Application templates should publish standard ingress ports in the tracked Compose file:

```yaml theme={null}
services:
  traefik:
    ports:
      - "80:80"
```

If the stack serves HTTPS directly, publish `443:443` in the tracked Compose file as well. `sitectl` infers `URI_SCHEME=https` when the Compose project publishes target port `443` or Traefik declares an HTTPS entrypoint on `:443`; otherwise it uses `URI_SCHEME=http`.

For local development contexts, [`sitectl compose up`](/commands/compose) checks whether `80` or `443` is already occupied. If another process owns a needed port, it writes `docker-compose.override.yml` with a Compose `ports: !override` entry such as:

```yaml theme={null}
services:
  traefik:
    ports: !override
      - "8443:443"
```

That smart port allocation is a development convenience only. It should not be committed and should not be part of production deployment.

## Local HTTPS

If production runs HTTPS and a developer wants the local site to behave the same way, use mkcert-backed Traefik TLS:

```bash theme={null}
sitectl traefik tls mkcert --domain app.localhost
sitectl compose up --remove-orphans -d
```

See [Traefik service commands](/plugins/traefik) for TLS modes and [Compose commands](/commands/compose) for the local port behavior.