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.
Create a project
Section titled “Create a project”- Open Projects and click Create Project.
- Enter a name, and pick the agent from the name field.
- Paste or write the Compose YAML.
- 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
.envnext to the Compose file. Without it, no.envis created. - Click Create Project, or press
Ctrl/Cmd+S. Arcane saves the project, stopped, and opens it. - Click Up to deploy it. If the Compose file has a
build:section, the button reads Build & Deploy.
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.enveditor keeps the existing file. Different.envcontent is rejected. - Otherwise, Arcane adds a number to the name, such as
myapp-1.
Control a project
Section titled “Control a project”| 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. |
Set deploy options
Section titled “Set deploy options”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.
Watch deploy output live
Section titled “Watch deploy output live”- Open the dropdown on Deploy, Redeploy, or Pull.
- 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.
Fix deploy timeouts
Section titled “Fix deploy timeouts”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_healthymust define a healthcheck.
Browse projects
Section titled “Browse projects”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 ascom.example.team=media. - A project matches when any of its service containers has that label.
- Labels are separate from colored tags.
Manage project files
Section titled “Manage project files”- 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.
- 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.
- Click Save, or press
Ctrl/Cmd+S. Changes stay staged until you save.
| 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
.envgets Add .env file in the tree’s menu. Saving an empty.envremoves 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
.envfrom 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.
Tag projects
Section titled “Tag projects”- Open Create Project, a project’s table row, or its detail header.
- Click +.
- 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: purpleTag 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.
Rename a project with managed volumes
Section titled “Rename a project with managed volumes”Stop the project first. When you rename it, Arcane:
- Copies its Compose-managed volumes to new names.
- Updates the project.
- 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.
Sync with Git
Section titled “Sync with Git”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.
Build images from a project
Section titled “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.
Reference
Section titled “Reference”Where projects live
Section titled “Where projects live”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.
Additional projects directories
Section titled “Additional projects directories”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>toarcane-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.
Nested folders and symlinks
Section titled “Nested folders and symlinks”- 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 withdocker 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.
What deploys pull
Section titled “What deploys pull”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: imagevolume sources are pulled only if missing.
Supported Compose filenames
Section titled “Supported Compose filenames”compose.yaml/compose.ymldocker-compose.yaml/docker-compose.ymlpodman-compose.yaml/podman-compose.yml- One unambiguous custom
.yaml/.ymlfile in the project folder
How Arcane picks a Compose file
Section titled “How Arcane picks a Compose file”When a folder has more than one YAML file, Arcane picks in this order:
- A standard name from above.
- A custom file named after the folder (for example
radarr.yamlinRadarr-3/). - A single custom file with
composein its name. - Any single visible
.yaml/.ymlfile.
If two or more custom files are equally likely, Arcane reports the folder as ambiguous instead of guessing.
Compose environment variables
Section titled “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_FILEandCOMPOSE_ENV_FILESresolve 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
Section titled “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_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.