# Compose Service

URL: /docs/services/compose

Source: https://github.com/easypanel-io/monorepo/blob/main/apps/website/content/docs/services/compose.mdx

Deploy and operate multi-container applications with Docker Compose.



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 [#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 [#source]

### Inline [#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:

```yaml
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]

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.

<Callout type="info">
  Source changes update the service configuration, but the running containers
  change only after a deployment.
</Callout>

## Compose compatibility [#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 [#environment]

Store Compose interpolation variables in `.env` format:

```dotenv
APP_TAG=1.4.0
DATABASE_PASSWORD=change-me
```

They can be referenced from the Compose file:

```yaml
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.

<Callout type="warn">
  Environment values can contain secrets. Do not print them in build output or
  commit them to the Compose repository.
</Callout>

## Deployments [#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 [#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 [#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 [#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 [#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]

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 [#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 [#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.

<Callout type="warn">
  Destroying a Compose service permanently removes the service and its files.
  Export important data and verify external backups before confirming deletion.
</Callout>