Compose Service

A Compose service deploys multiple containers from one Docker Compose configuration. Use it when an application is already distributed as a Compose file or when several tightly related containers should be deployed together.

Easypanel manages the Compose deployment, logs, domains, redirects, basic authentication, environment variables, deployment triggers, and maintenance mode. Settings that are normally managed by Easypanel should be configured in the panel instead of duplicated in the Compose file.

Create a Compose service

1. Open a project and select New Service.
2. Select Compose and enter a service name.
3. Choose an inline or Git source.
4. Review any compatibility issues reported by Easypanel.
5. Deploy the service.
6. Add a domain and select the internal Compose service and port that should receive traffic.

Source

Inline

Inline source stores the Compose YAML directly in Easypanel. It is useful for small configurations or workloads that do not need a separate repository.

For example:

services:
  web:
    image: nginx:alpine
    volumes:
      - site-data:/usr/share/nginx/html

volumes:
  site-data:

After deploying this example, a domain can route to the web service on port 80.

Git

Git source loads the Compose configuration from a repository. Configure:

• Repository URL: the Git repository URL;
• Branch: the Git branch or ref to deploy;
• Build Path: the repository directory used as the Compose project root;
• Docker Compose File: the Compose filename relative to the build path.

The build path must start with /. For a private repository, add the service-specific SSH key shown by Easypanel as a read-only deploy key. Refreshing the key requires updating it at the Git provider.

Compose compatibility

Easypanel checks the Compose configuration for settings that can conflict with other services. It currently reports:

• container_name, because a fixed container name can collide with another Compose project;
• ports, because a published host port must be unique across the server.

Resolve these warnings before relying on the deployment. Prefer Easypanel domains over ports for public HTTP traffic, and let Compose generate scoped container names instead of setting container_name.

Keep the Compose file focused on containers, images, build instructions, commands, health checks, dependencies, and persistent volumes. Configure public HTTP routing, HTTPS, redirects, and basic authentication in the corresponding Easypanel sections.

Relative build contexts and referenced files are resolved from the configured build path. Make sure every required file is present in the Git repository.

Environment

Store Compose interpolation variables in .env format:

APP_TAG=1.4.0
DATABASE_PASSWORD=change-me

They can be referenced from the Compose file:

services:
  app:
    image: example/app:${APP_TAG}
    environment:
      DATABASE_PASSWORD: ${DATABASE_PASSWORD}

Enable Create .env file to write these values to .env in the configured build path. Docker Compose reads that file for interpolation. For a Git source, Easypanel automatically copies .env.example into the environment editor and enables .env creation when the repository has no .env and the service has no saved environment values.

Redeploy after changing environment values.

Deployments

Use Deploy after changing the source or environment. Easypanel runs docker compose up --build -d, so services with a build section are rebuilt as part of the deployment.

The Deployment Trigger URL starts a deployment from a Git provider, CI pipeline, or other external system. Refreshing the deployment token invalidates the previous URL.

Logs

Compose logs can be filtered by internal service, time range, log level, standard output or standard error, and text search. Select the individual container service when a multi-container deployment produces interleaved logs.

If a deployment fails before containers start, inspect the deployment output and Compose issues in addition to the runtime log view.

Domains

A Compose domain routes traffic to one internal service from the Compose file. Configure:

• the public hostname and optional path;
• the internal Compose service;
• the target container port;
• HTTP or HTTPS for the internal connection;
• the certificate resolver and optional Traefik middlewares.

Do not point a domain at a database, queue, or other service that should remain private. Use a published port only when a non-HTTP service must be reachable outside the Docker network.

Redirects

Redirect rules match a regular expression and send requests to a replacement URL. A rule can be temporary or permanent and can be disabled without deleting it.

Use temporary redirects while testing. Browsers can cache permanent redirects, making a bad rule harder to reverse.

Security

The Security section configures HTTP Basic Auth for the public domains attached to the Compose service. Add one or more username and password pairs to protect staging sites or internal tools.

Basic Auth protects requests at the proxy. It does not control communication between Compose containers and does not replace application-level authorization.

Maintenance

Maintenance mode replaces normal domain traffic with a maintenance page. The page can define a title and subtitle. Licenses that support white-labeling can also configure a custom logo, custom CSS, and whether Easypanel branding and links are visible.

Maintenance mode does not stop the containers. Use it when a migration or deployment must continue without serving normal user traffic.

Persistent data

Declare persistent application data as named volumes or explicit bind mounts in the Compose file. Container filesystem changes that are not stored in a volume can be lost when a container is recreated.

Back up databases and uploaded files before changing volume definitions, renaming Compose services, or deleting the Compose service.

Service lifecycle

• Start enables and starts the Compose deployment.
• Stop stops the containers and disables the service.
• Restart restarts all containers in the service.
• Deploy applies the current source and environment.