Stacks

A stack is an application group that a docker-compose file defines. Reoclo deploys all of its services together, as one coordinated deployment.

Reoclo creates one member application for each service in the compose file. When you push, Reoclo builds only the services that changed and starts the stack in dependency order.

Stacks compared to manual groups

A manual group is a label. You group applications by hand and deploy them together with one action. Each application still builds and deploys on its own. See Application Groups.

A stack works from a definition. A docker-compose file defines the stack. Reoclo reads the file, creates one member application per service, and deploys the services together in dependency order.

What Reoclo derives from the compose file

For each service in the file, Reoclo creates one member application. Reoclo derives the build configuration from the compose definition:

• Build pack
• Compose file path
• Compose service name
• Container port
• Health check path

These fields are read-only on a member application. The compose file is the source of truth.

Do not move or rename the compose file in a repository refactor without a plan. Reoclo matches the stack to the file by its path, so a moved file orphans every member on the next sync. Create the stack again from the new path, or restore the old path.

Each member application keeps its own editable settings:

• Environment variables
• Secret bindings
• Domains
• Monitors
• Service connections

Reoclo scopes this configuration per service. Reoclo never shares one .env across every service.

Orphaned services

If you remove a service from the compose file, Reoclo marks its member application as orphaned. An orphaned member does not deploy, and it does not count against the stack’s health. On the next deploy, Docker Compose removes the service’s containers, because they are no longer part of the stack. To keep a container, for example a database you still read data from, keep its service in the compose file.

The member application record stays visible until you act on it. To remove every orphaned member in one command, run reoclo stacks prune <stack>. Without --yes, the command only lists the orphaned members. With --yes, it removes them.

Secrets for a stack

A secret project linked at the stack level injects into every member on deploy. A member’s own linked projects and explicit variables override the stack layer on name collisions.

To give a member only part of a project, edit the binding and select keys. A selection can also rename a key, so one stored credential injects under two names. For example: MINIO_ROOT_USER for the storage service, and S3_ACCESS_KEY_ID for the applications that call it.

Creating a stack

Two flows create a stack.

From the setup wizard

1. Start the application setup wizard.
2. Connect the repository that holds your compose file.
3. Wait for the scan to find the compose services.
4. Choose Deploy as one stack.
5. Select the server that runs the stack.
6. Click Create.

The other option in the wizard, Separate applications, keeps the previous per-application behavior.

Compose files the scan finds

The scan finds compose files by name, in every directory of the repository:

• Names that start with compose or docker-compose, for example docker-compose.yml or compose.prod.yaml
• Names that end with .compose.yml or .compose.yaml, for example admin.compose.yml

If your file uses a different name, add it by path. On the scan step, open Add a config file by path and enter the path from the repository root, for example deploy/app.yaml. Reoclo reads the file at the selected branch and adds its services to the results. If the file does not resolve, the scan shows the reason under the path.

A stack runs on one server. Compose is single-host, so all of the services deploy to the same server.

From the Service Directory

The Service Directory has open-source templates that deploy as a stack. DocuSeal and Documenso are two examples.

1. Open the Service Directory.
2. Choose a compose template.
3. Enter the template parameters.
4. Select the target server.
5. Click Deploy.

Reoclo compiles the template into a stack with one member application per service. Generated parameters, such as passwords, fill in for you.

More than one stack from one repository

You can create more than one stack from the same repository, for example one for staging and one for production. Give each stack a different name.

Member slugs are unique across your organization. If another stack already uses a service slug, Reoclo names the new member <stack>-<service>. For example, a second stack named portfolio-staging gets the members portfolio-staging-frontend and portfolio-staging-backend. The first stack keeps its members unchanged.

A member slug is not the compose service name. CLI commands that take --app expect the member slug. A slug does not change after Reoclo creates the member, so members added at different times can carry different prefixes in one stack. Run reoclo apps ls or reoclo stacks get <stack> to see the slugs.

If your compose file sets container_name, Docker permits only one container with that name on a server. Deploy the second stack to a different server, or remove container_name from the file.

Deploying a stack

When you deploy a stack, Reoclo runs one coordinated deployment for all of the services. This is a stack deployment. One push creates one stack deployment, with one child deployment per service underneath it.

The branch a stack deploys

A stack deploys one branch of its repository. The wizard records the branch you scanned at setup. A push starts a stack deployment only for commits to this branch. Manual deployments and redeploys also build this branch.

When no branch is set, the stack deploys the repository’s default branch. To change the branch, open the stack’s Settings tab and edit Deploy Branch.

A stack deployment runs these steps:

1. Precheck validates the compose file and the server.
2. Clone clones the repository a single time, not one clone for each service.
3. Plan compares the compose file against the running state and decides a per-service action.
4. Build builds the changed services. Independent builds run in parallel.
5. Up starts the services in dependency order.
6. Verify checks each service against its compose health check.
7. Cleanup removes the build artifacts.

Build only what changed

The plan step gives each service one action:

Action	Meaning
build	Reoclo rebuilds the image.
pull	Reoclo pulls a new image.
recreate	Reoclo recreates the container.
restart	Reoclo restarts the container.
unchanged	Reoclo does not change the service.

A service rebuilds only when something that affects it changed:

• Its build context or Dockerfile changed in the commit.
• Its section of the compose file changed.
• Its environment variables or secrets changed.

Reoclo does not recreate unchanged services. A change to one service does not restart your database.

Image pulls

A service whose image tag exists only on the server (built or tagged outside Reoclo) fails the pull with “manifest unknown”. Push that image to a registry, or give the service a build key.

Dependency order and health

Reoclo follows your compose file. Reoclo does not rewrite your container_name, restart:, volumes, or depends_on.

Reoclo starts the services in the order that depends_on sets. Where the file sets condition: service_healthy, Reoclo waits for the service to become healthy first. Reoclo reads the compose health checks to confirm that each service is healthy.

Reoclo also follows compose profiles. A service under profiles: is not part of the default deploy set. It becomes a task member: a one-shot job that no other service waits for, for example a bucket-init container.

Compose does not let a service depends_on a profiled service. A database migration is the usual case: the application waits on it with condition: service_completed_successfully. For that job, use the reoclo.task label instead of profiles::

services:
  migrate:
    build: ./migrate
    labels:
      reoclo.task: "true"

A labeled task member deploys with the stack, so compose keeps the dependency order and a failed migration stops the deploy. Reoclo counts the container as healthy when it exits with code 0, and shows the member as stopped.

A profiled task member does not deploy with the stack. Neither kind of task member counts against the stack’s health. To run a task member on demand, click Run on the member in the stack’s members list. Reoclo runs docker compose run --rm for the service, with the stack’s environment files applied. Reoclo records each run with its exit code and its last log lines. Exit code 0 is success.

Deploy the stack one time before you run a task. The run uses the environment files from the last stack deployment.

An existing stack picks up the task classification on its next deploy, or when you click Resync on the stack.

When the compose file defines a healthcheck: for a service, Reoclo copies it into the member’s health check configuration. An operator’s own health check setting always wins over the copied value.

If a value in your compose file conflicts with a Reoclo rule, the deployment fails at precheck. Reoclo returns a readable message instead of rewriting your file.

When a service fails

If a service build fails, Reoclo stops the services that depend on it. Reoclo leaves the unchanged services running.

Reoclo marks the stack deployment failed. If independent services still succeeded, Reoclo marks it partial instead.

A rollback re-runs the last successful plan. It restores the previous images and the previous compose file.

The stack page

Each stack has its own page. The header shows the stack health at a glance.

Under the header, a topology canvas shows the stack. Each service is a node with its status, container state, and domains. The edges show the depends_on and connection links between the services.

From a service node, you can:

• Open its logs
• Restart the service
• Redeploy the service
• Open its member application

The stack deployment view shows the pipeline as a graph: clone, plan, parallel builds, ordered up, and verify. Select a service node to open that service’s build log.

Per-service actions

A stack does not force you to redeploy everything. You can act on one service.

• Restart a service restarts its container.
• Redeploy a service rebuilds and starts that one service.

Each per-service action is a stack deployment with a single-service plan. Your deployment history stays in one place.

A redeploy of an unchanged service does not replace its container: docker compose up only recreates what changed. To replace it anyway, select Force recreate containers in the redeploy dialog, or pass --force-recreate to reoclo groups redeploy. A forced scoped redeploy recreates only the named service.

Auto-deploy on push

Set Auto-deploy on the stack to deploy on every push. A push to the stack’s repository and branch creates one stack deployment.

For a stack, Reoclo ignores the per-application auto-deploy setting. The stack-level setting controls the deploy.

Environment variables and secrets

Reoclo scopes environment variables per service. Each member application keeps its own variables and secret bindings.

The plan step counts an environment or secret change as a change to that service. A secret change therefore redeploys only the service that uses it.

Managing a stack from the Applications list

The Applications list is a control plane. From the list, you can deploy, restart, stop, or delete a whole stack. You can also select services and run a bulk action.

Limitations

• A stack runs on one server. Compose is single-host.
• For a git-sourced stack, the compose file is read-only in Reoclo. Edit the file in your repository, and the next push updates the stack.

Next Steps

• Application Groups for manual groups
• Deployment Configuration for per-application settings
• GitHub App Setup to connect repositories