Projects

A project is a folder with a Compose file and its related files, such as .env and config files, that Arcane deploys and manages as one unit. Use a project whenever you would otherwise run docker compose up: for an app made of several services, or for any container you want defined in a file you can edit, version, and redeploy. The Containers page manages individual containers, including ones started outside Arcane.

Where projects live

Each project is a folder inside the Projects Directory: /app/data/projects by default, or the absolute path you set with PROJECTS_DIRECTORY or on the environment’s Storage & Limits tab. Arcane saves the Compose file and .env there, and scans the directory, including nested folders, for Compose files, so projects created outside Arcane show up too. Folders with the same name are told apart by their full paths.

Mounting the folder at the same path on the host and in the container is the simplest setup. Installation explains the mount and how Arcane translates paths when they differ.

Browse projects

Open Projects in the sidebar. The list shows project name, status (running, partially running, stopped), service count, and the project directory.

Use the Labels filter to find projects with a container label. Enter a key such as com.example.team, or an exact match such as com.example.team=media. A project matches when at least one of its existing service containers has that label. This is separate from the project’s colored tags.

Create a project

1. Click Create Project.
2. Enter a name.
3. Paste or write the Compose YAML.
4. Optional: open the Environment Configuration (.env) editor and add variables. Arcane saves them to a .env file next to the Compose file.
5. Click Create Project. Arcane saves the project and tries to start it.

Control a project

• Up: start all services.
• Down: stop and remove all containers.
• Restart: stop and start without recreating containers.
• Redeploy: pull the latest images and restart.
• Destroy: remove the project and its resources. You choose whether to keep or delete volumes and project files.

Set deploy options

Open the Deploy dropdown to set:

• Pull policy: pull if not present, always pull latest, or never pull. It starts from the environment’s Default Deploy Pull Policy (Environments → the environment → Docker) until you change it here.
• Force recreate containers: recreate every container even if nothing about it changed.
• Recreate changed volumes (data loss): allow Compose to recreate a volume whose configuration no longer matches the Compose file.

Arcane remembers pull policy and force recreate. Recreate changed volumes resets after each deploy because it destroys data. For bulk Up, it applies to the whole batch.

Deploys pull service image: references, lifecycle hook images such as pre_start, and type: image volume sources. Hook and volume images are also pulled for services with build:. Hook and volume images follow the service’s pull policy, except type: image volume sources, which are pulled only if missing.

Set the deploy wait timeout

A deploy waits for depends_on conditions such as service_healthy and service_completed_successfully. If slow healthchecks or initialization cause timeouts, raise Deploy Wait Timeout in Settings → Timeouts. The default is 600 seconds; the range is 30–14400. Dependencies using service_healthy must define a healthcheck.

Watch deploy output live

Deploy, Redeploy, and Pull are split buttons. Open the dropdown next to any of them and choose Watch output to run that action in an attached terminal window instead of in the background. The window streams Docker output. Deploy and Redeploy keep streaming container logs after startup, like an attached docker compose up.

Choose Watch output per run. Otherwise, actions run in the background under Activity & Events.

Manage project files

Turn on Workspace to browse project files in a tree and edit them in tabs. It’s also available on Create Project for adding files before the first deploy.

From the workspace panel you can:

• New File / New Folder: create files and folders anywhere in the project, including nested paths.
• Upload File: add a file from your computer, including binary files, up to 10 MiB by default.
• Edit: open any UTF-8 text file in its own tab. Binary files can be uploaded but not edited.
• Rename, Move, and Delete: reorganize the folder. Non-empty folders can be deleted recursively.

All file changes are staged until you Save the project. Build and dependency folders (.git, node_modules, vendor, dist, build, and similar) are hidden from the tree. For projects using Git Pull, files managed by the sync are read-only; other workspace files stay editable.

The file size, depth, and entry limits are set by environment variables listed under Reference.

Sync from Git

A Git sync connects a project to a repository in one of two directions. Pull deploys from Git: you edit files in the repository, and Arcane pulls them in and can redeploy the project. Push backs up to Git: you keep editing in Arcane, and Arcane commits the project’s files to the repository without deploying or restarting anything.

A project can have one Git sync. To change its direction, disconnect the existing sync and create a new one. Git Sync covers connecting a repository, setting up each direction, and resolving conflicts.

Build images from a project

If a service in the Compose file has a build: directive, the project page shows Build and Build & Deploy. Image Builds covers build providers, history, and the build API.

Tag projects

Add colored tags when creating a project or from its table row or detail header. Click +, then use Search or create a tag… to select an existing tag or create one with a color. Click a selected tag to remove it. Extra tags appear under +N after the first three.

Filter the Tags column to match any selected tag, or search by tag name.

Tags can also be declared in the Compose file itself, under the x-arcane extension block:

x-arcane:
  tags:
    - name: database
      color: purple

Compose-defined tags are applied on deploy and sync, and are read-only in Arcane. They show a lock icon and can only be changed by editing the Compose file.

• Tag names are trimmed and lowercased, up to 64 characters, with no commas.
• A tag name’s color is shared everywhere it’s used; attaching an existing name keeps its stored color.
• Each project holds up to 50 UI tags and 50 Compose tags.
• The tag catalog is per environment.
• Editing tags requires the projects:update permission. Discovered (unmanaged) projects can’t be tagged.

Rename a project with managed volumes

Renaming a stopped project copies its Compose-managed volumes to their new names, updates the project, then removes the old volumes. Volumes with an explicit name: or external: true are left alone.

The rename is blocked if:

• the project is still running
• the target volume name already exists
• a source volume is still attached to a container
• Docker reports insufficient space to copy the volume data

Nested folders and symlinks

For symlinked layouts (for example GNU Stow), turn on Follow Project Symlinks on the environment’s Storage & Limits tab so Arcane follows child-directory symlinks.

A folder Arcane can’t read appears empty. Other folders remain accessible.

Compose files that reference paths outside the projects mount with a relative path (such as ../../data:/app/data) are resolved against the host projects directory, so they behave the same as running docker compose up yourself. include: entries may also point outside the project directory, for example a shared fragment kept next to several projects (include: [../shared.yaml]).

Reference

Supported Compose filenames

Arcane recognizes any of these as the project’s Compose file:

• compose.yaml / compose.yml
• docker-compose.yaml / docker-compose.yml
• podman-compose.yaml / podman-compose.yml
• a single custom .yaml / .yml file in the project folder, when it’s unambiguous

How Arcane picks a Compose file

When a folder has more than one YAML file, Arcane chooses in this order:

1. A name from the list above.
2. A custom file whose name matches the folder name (for example radarr.yaml in Radarr-3/).
3. A single custom file with compose in its name.
4. Any single visible .yaml / .yml file.

If two or more custom files are equally plausible, Arcane reports the directory as ambiguous instead of guessing.

Compose environment variables

Arcane honors these Docker Compose pre-defined environment variables when they are set in the project’s .env file:

Paths in COMPOSE_FILE and COMPOSE_ENV_FILES resolve relative to the project folder and must stay inside it; an entry that points outside the project is rejected.

When COMPOSE_FILE selects more than one file, the project detail view shows a Multiple compose files card listing them. The base file opens in the Compose editor; edit the others in Workspace.

Workspace limits

Set these on the Arcane container to change the workspace limits: