Projects

A project is a folder with a Compose file and related files, such as .env and config files, that Arcane deploys and manages as one unit. Use one wherever you’d run docker compose up. To manage individual containers, including ones started outside Arcane, use Containers.

Manage related services together as a Compose project.

×

Manage related services together as a Compose project.

Where projects live

Each project is a folder in the Projects Directory: /app/data/projects by default, or the absolute path set with ARCANE_PROJECTS_DIRECTORY or under Settings → Storage & Limits. Arcane scans it, including nested folders, for Compose files, so projects created outside Arcane show up too. Same-named folders are told apart by full path.

Mounting the folder at the same path on host and container is simplest. Installation explains the mount and path translation when they differ.

Browse projects

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

The Labels filter takes a key such as com.example.team or an exact match such as com.example.team=media. A project matches when any existing service container has that label. This is separate from colored tags.

Create a project

1. Click Create Project, enter a name, and pick the environment from the name field.
2. Paste or write the Compose YAML.
3. Optional: add variables in the Environment Configuration (.env) editor, saved to .env next to the Compose file. Leave it empty and no .env is created.
4. Click Create Project, or press Ctrl/Cmd+S. Arcane saves the project and tries to start it.

The folder is named after the project. If a same-named folder exists with no Compose file and no other project using it, Arcane uses it and keeps its files; an existing .env is kept if the .env editor is empty, and different content is rejected. Otherwise Arcane adds a number, such as myapp-1.

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. Defaults to the environment’s Default Deploy Pull Policy (Settings → Docker).
• Force recreate containers: recreate every container even if unchanged.
• Recreate changed volumes (data loss): let Compose 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, and applies to the whole batch for bulk Up.

Warning

Applying a changed volume configuration destroys and rebuilds the volume, losing its data. Arcane refuses unless Recreate changed volumes is checked. The deploy log explains a refusal with Declined; enable volume recreation on deploy to apply this change.

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

Set the deploy wait timeout

Deploys wait for depends_on conditions such as service_healthy and service_completed_successfully. If slow startup causes timeouts, raise Deploy Wait Timeout (Settings → Timeouts): default 600 seconds, range 30–14400. Dependencies using service_healthy must define a healthcheck.

Watch deploy output live

Deploy, Redeploy, and Pull are split buttons. Choose Watch output from the dropdown to run the action in an attached terminal window streaming Docker output. Deploy and Redeploy keep streaming container logs after startup, like an attached docker compose up. Otherwise, actions run in the background under Activity & Events.

Warning

Closing the watch window for Deploy or Redeploy stops the project and all its containers, like Ctrl-C on an attached docker compose up. Arcane asks Stop project? before doing so. To keep the project running, leave the window open; you can also follow the operation in the Activity Center.

Manage project files

Turn on Workspace to browse project files in a tree and edit them in tabs, also on Create Project before the first deploy:

• New File / New Folder: create anywhere, including nested paths.
• Upload File: add any file, including binary, up to 10 MiB by default.
• Edit: open UTF-8 text files in tabs. Binary files can’t be edited.
• Rename, Move, and Delete: reorganize. Non-empty folders delete recursively.

Right-click a file or folder for these actions, or empty space to create or upload. Right-click in the editor for cut, copy, paste, and editor commands.

Changes are staged until you Save or press Ctrl/Cmd+S. Middle-click a tab to close it. Build and dependency folders (.git, node_modules, vendor, dist, build, and similar) are hidden. For Git Pull projects, sync-managed files are read-only.

Note

The Compose file, .env, .env.git, and project.env are protected. They show a lock icon and can’t be renamed, moved, or deleted from the tree; use their own editors.

File size, depth, and entry limits are set under Workspace limits.

Review and edit the Compose configuration alongside its environment file.

×

Review and edit the Compose configuration alongside its environment file.

Sync from Git

Pull deploys from Git: you edit in the repository, and Arcane pulls the files and can redeploy. Push backs up to Git: you edit in Arcane, and it commits the files without deploying or restarting. A project has one sync; to change direction, disconnect and create a new one. See Git Sync.

Build images from a project

If a service has a build: directive, the project page shows Build and Build & Deploy. See Image Builds for providers, history, and the build API.

Note

If you use Depot or push images, services should set explicit image: names. Arcane blocks generated local-only tags in that case.

Tag projects

Add colored tags when creating a project, or from its table row or detail header. Click +, then Search or create a tag… to pick or create one with a color. Click a selected tag to remove it. Tags beyond three collapse under +N. Filter the Tags column by any selected tag, or search by name.

You can also declare tags in the Compose file’s x-arcane block:

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

Compose-defined tags apply on deploy and sync and show a lock icon; change them only in 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 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 running, a target volume name exists, a source volume is attached to a container, or Docker reports insufficient space for the copy.

Nested folders and symlinks

For symlinked layouts (for example GNU Stow), turn on Follow Project Symlinks under Settings → Storage & Limits so Arcane follows child-directory symlinks.

Note

On Linux, deeply nested project trees consume extra inotify watches because Arcane monitors them recursively. For very large trees, raise fs.inotify.max_user_watches.

A folder Arcane can’t read appears empty; others stay accessible.

Relative paths outside the projects mount (such as ../../data:/app/data) resolve against the host projects directory, as with docker compose up. include: entries may also point outside the project, such as a shared fragment (include: [../shared.yaml]).

Reference

Supported Compose filenames

Arcane recognizes compose.yaml / compose.yml, docker-compose.yaml / docker-compose.yml, podman-compose.yaml / podman-compose.yml, and a single unambiguous custom .yaml / .yml file in the project folder.

How Arcane picks a Compose file

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

1. A standard name from 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 in the project’s .env:

Variable	Effect
COMPOSE_FILE	Deploy a specific Compose file, or several merged in order. Separate entries with : (or the value of COMPOSE_PATH_SEPARATOR). The first entry is the base file.
COMPOSE_PROFILES	Comma-separated list of profiles to activate.
COMPOSE_PROJECT_NAME	Override the project name Compose uses.
COMPOSE_ENV_FILES	Additional env files to load, in order.
COMPOSE_REMOVE_ORPHANS / COMPOSE_IGNORE_ORPHANS	Control how containers left over from removed services are handled.
COMPOSE_PARALLEL_LIMIT	Cap how many operations Compose runs at once.

Paths in COMPOSE_FILE and COMPOSE_ENV_FILES resolve relative to the project folder; entries outside it are rejected. With several files, the detail view lists them in a Multiple compose files card. The base file opens in the Compose editor; edit the others in Workspace.

Workspace limits

Set these on the Arcane container:

Variable	Default	Sets
ARCANE_PROJECT_WORKSPACE_MAX_FILE_SIZE_MB	10	Maximum size of a single workspace file, in MiB
ARCANE_PROJECT_WORKSPACE_MAX_DEPTH	20	Maximum folder depth
ARCANE_PROJECT_WORKSPACE_MAX_ENTRIES	2000	Maximum number of files and folders

Important

Use ARCANE_PROJECT_WORKSPACE_MAX_DEPTH to set the folder depth. Arcane doesn’t read PROJECT_FILE_TREE_MAX_DEPTH, so rename it if your environment still sets it.