# Docker Environment Composition

This repo uses multi-file Docker Compose with a wrapper script as the composition entrypoint.

## Composition source of truth

`services-up.sh` is the composition authority for this repository.

It:

1. discovers compose files under `apps/`, `monitoring/`, and `core/`,
2. prepends shared baseline files,
3. applies `default-environment.env` and `secrets/stack-secrets.env`,
4. invokes `docker compose` with a stable project name.

Because of this, when validating or understanding runtime composition, prefer running:

```bash
./services-up.sh --profile all config
```

## Inputs used by `services-up.sh`

- `default-network.yml`
- discovered `docker-compose.yml` / `docker-compose.yaml` files under `core/`, `apps/`, `monitoring/`
- `default-environment.env`
- `secrets/stack-secrets.env` (local, not committed)

## Typical workflows

### Validate final composed model

```bash
./services-up.sh --profile all config
```

Use this to review merged services, networks, volumes, profiles, and environment substitution.

### Validate one compose file directly

```bash
docker compose -f apps/nextcloud/docker-compose.yml config
```

Use this when focused on one service family.

### Deployment prerequisites

Before runtime operations, follow [DEPLOYMENT.md](../DEPLOYMENT.md) to create required local secret files.

## What not to do

- Do not treat archived compose files in `archive/` as active runtime definitions.
- Do not hardcode secrets in committed compose files.
- Do not bypass `services-up.sh` when trying to understand full active composition.

## Related docs

- [docs/source-of-truth.md](source-of-truth.md)
- [docs/repo-structure.md](repo-structure.md)
- [docs/architecture.md](architecture.md)