Skip to content

Projects

Create, deploy, and edit Docker Compose projects in Arcane.

A project is a folder with a Compose file and its related files (.env, config files) that Arcane deploys as one unit. To manage single containers, including ones started outside Arcane, use Containers.

  1. Open Projects and click Create Project.
  2. Enter a name, and pick the agent from the name field.
  3. Paste or write the Compose YAML.
  4. Optional: click Add .env file to add project variables. In Workspace view, right-click empty space in the file tree instead. They’re saved to .env next to the Compose file. Without it, no .env is created.
  5. Click Create Project, or press Ctrl/Cmd+S. Arcane saves the project, stopped, and opens it.
  6. Click Up to deploy it. If the Compose file has a build: section, the button reads Build & Deploy.
After Up, the project shows as Running in the Projects list.
The Projects list showing the demo project as Running with 3 services.The Projects list showing the demo project as Running with 3 services.

After Up, the project shows as Running in the Projects list.

How Arcane picks the folder:

  • The folder is named after the project.
  • If a folder with that name already exists, has no Compose file, and no other project uses it, Arcane reuses it and keeps its files.
  • When it reuses a folder with a .env, an empty .env editor keeps the existing file. Different .env content is rejected.
  • Otherwise, Arcane adds a number to the name, such as myapp-1.
Action What it does
Up Starts all services.
Down Stops and removes all containers.
Restart Stops and starts without recreating containers.
Redeploy Pulls the latest images and restarts.
Destroy Removes the project and its resources. You choose whether to keep volumes and files.

Open the Deploy dropdown:

  • Pull policy: pull if not present, always pull latest, or never pull. Defaults to the agent’s Default Deploy Pull Policy (Settings → Docker).
  • Force recreate containers: recreate every container, even unchanged ones.
  • 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. For a bulk Up, it applies to the whole batch.

  1. Open the dropdown on Deploy, Redeploy, or Pull.
  2. Choose Watch output.

A terminal window streams Docker output. Deploy and Redeploy keep streaming container logs after startup, like an attached docker compose up. Without Watch output, actions run in the background under Activity & Events.

Deploys wait for depends_on conditions such as service_healthy and service_completed_successfully. If slow startups time out, raise Deploy Wait Timeout under Settings → Timeouts.

  • Default: 600 seconds. Range: 30 to 14400.
  • Dependencies using service_healthy must define a healthcheck.

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

To filter by Docker label, use the Labels filter:

  • Enter a key, such as com.example.team, or an exact match, such as com.example.team=media.
  • A project matches when any of its service containers has that label.
  • Labels are separate from colored tags.
  1. Turn on Workspace. It also works on Create Project, before the first deploy. It’s on by default; change the default with Default project editor layout in Preferences.
  2. Right-click a file or folder to act on it. Right-click empty space to create or upload. All file actions live in these menus.
  3. Click Save, or press Ctrl/Cmd+S. Changes stay staged until you save.
The project workspace with the Compose file open.
The Compose editor for a running project with web, cache, and worker services.The Compose editor for a running project with web, cache, and worker services.

The project workspace with the Compose file open.

Action Notes
New File / New Folder Anywhere, including nested paths.
Upload File Any file, including binary. Up to 10 MiB by default.
Edit UTF-8 text files open in tabs. Binary files can’t be edited.
Rename, Move, Delete Non-empty folders delete recursively.
  • Right-click in the editor for cut, copy, paste, select all, and editor commands. Middle-click a tab to close it.
  • The tab strip shows the open file’s validation errors, schema, and cursor position.
  • Indentation follows Editor tab width in Preferences.
  • A project without a .env gets Add .env file in the tree’s menu. Saving an empty .env removes the file.
  • Build and dependency folders (.git, node_modules, vendor, dist, build, and similar) are hidden.
  • The Compose and override files show a lock icon. You can’t rename, move, or delete them from the tree.
  • Delete .env from its own menu.
  • For Git Pull projects, sync-managed files are read-only.

The tree loads a folder’s contents when you open it. Size and per-folder entry limits: see Workspace limits.

  1. Open Create Project, a project’s table row, or its detail header.
  2. Click +.
  3. In Search or create a tag…, pick a tag, or type a new name and choose a color.
  • To remove a tag, click it.
  • More than three tags collapse under +N.
  • To filter, use the Tags column, or search by tag name.

You can also declare tags in the Compose file’s x-arcane block. They apply on deploy and sync, show a lock icon, and can only be changed in the Compose file.

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

Tag rules:

  • Names are trimmed and lowercased, up to 64 characters, with no commas.
  • A tag name has one color everywhere. 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 agent.
  • Editing tags needs projects:update. Discovered (unmanaged) projects can’t be tagged.

Stop the project first. When you rename it, Arcane:

  1. Copies its Compose-managed volumes to new names.
  2. Updates the project.
  3. Removes the old volumes.

Volumes with an explicit name: or external: true are left alone.

Renaming is blocked when:

  • The project is running.
  • A target volume name already exists.
  • A source volume is attached to a container.
  • Docker reports there isn’t enough space for the copy.

A project can have one sync. To change direction, disconnect it and create a new one. See Git Sync.

  • Pull deploys from Git. You edit in the repository; Arcane pulls the files and can redeploy.
  • Push backs up to Git. You edit in Arcane; it commits the files without deploying or restarting.
  • Pull and push syncs both ways. You edit in either place; a file changed on both sides waits for you to pick a version.

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.

Each project is a folder in the Projects Directory. The default is /app/data/projects. Change it with ARCANE_PROJECTS_DIRECTORY or under Settings → Storage & Limits.

  • Arcane scans the folder, including nested folders, for Compose files. 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 covers the mount, and path translation when they differ.

Arcane can scan more folders for projects. Add them under Settings → Storage & Limits → Additional Project Directories, or set ARCANE_PROJECTS_DIRECTORIES to a JSON array:

environment:
- 'ARCANE_PROJECTS_DIRECTORIES=[{"path":"/opt/stacks","enabled":true}]'
  • Mount each folder into the Arcane container. The settings page flags paths it can’t find in the container.
  • Paths must be absolute. Each entry also accepts the <containerPath>:<hostPath> form.
  • Entries can’t repeat, sit inside one another, or overlap the Projects Directory or the Templates Directory.
  • A disabled entry is kept but not scanned.
  • New projects go in the Projects Directory. When more than one directory is enabled, pick another with the folder selector next to the project name, or pass --directory <containerPath> to arcane-cli projects create. Git syncs always create projects in the Projects Directory.
  • When projects come from more than one directory, the projects list shows each project’s directory in its path.
  • For symlinked layouts (for example GNU Stow), turn on Follow Project Symlinks under Settings → Storage & Limits. Arcane then follows child-directory symlinks.
  • A folder Arcane can’t read appears empty. Other folders 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 can point outside the project, such as a shared fragment (include: [../shared.yaml]).
  • On Linux, Arcane watches project trees recursively, so deep trees use extra inotify watches. For very large trees, raise fs.inotify.max_user_watches.

Deploys pull service image: references, lifecycle hook images such as pre_start, and type: image volume sources. This includes services with build:.

  • Hook images follow the service’s pull policy.
  • type: image volume sources are pulled only if missing.
  • compose.yaml / compose.yml
  • docker-compose.yaml / docker-compose.yml
  • podman-compose.yaml / podman-compose.yml
  • One unambiguous custom .yaml / .yml file in the project folder

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

  1. A standard name from above.
  2. A custom file named after the folder (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 likely, Arcane reports the folder as ambiguous instead of guessing.

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.

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_ENTRIES 2000 Maximum number of files and folders per folder
ARCANE_PROJECT_WORKSPACE_MAX_DEPTH 20 Maximum folder depth in the Build Workspace

A folder with more entries than the limit shows only its first entries. The workspace tells you when that happens. The project workspace has no depth limit.