Arcane

Deploying fewohbee with Arcane

This guide describes how to deploy fewohbee with Arcane using a Git sync.

Arcane uses the same Compose files as the Docker setup and Portainer. They need no files from the repository at runtime, so neither Sync Files nor a special mapping of Arcane's projects directory is required.

Table of Contents

• Prerequisites
• Creating the Project
• Initialize the Application
• Updates
• Backups
• Troubleshooting

---

Prerequisites

• Arcane is installed and a Docker environment is connected
• The host ports for HTTP and HTTPS are free (default 80 and 443, configurable via LISTEN_PORT and HTTPS_LISTEN_PORT)

Creating the Project

Step 1 – Add the Repository

Navigate to Customization → Git Repositories → Add Repository and enter:

Field	Value
Repository URL	https://github.com/developeregrem/fewohbee-dockerized.git
Authentication	The repository is public, no token or SSH key is required

Step 2 – Create the Git Sync

On the Projects page, open the dropdown next to Create Project and choose From Git Repo.

Field	Value
Sync direction	Pull
Sync Name	e.g. fewohbee (becomes the project name)
Target Type	Project
Project	Create a new project
Git Repository	the repository from step 1
Branch	master
Compose File Path	docker-compose.yml (standard, with SSL) or docker-compose.no-ssl.yml (reverse proxy, no SSL)
Sync Files	optional, not required
Auto Sync	on, e.g. every 60 minutes
Pull Image After Sync	off
Redeploy After Sync	off

Which compose file to choose?

• docker-compose.yml — for servers with direct internet access. Manages SSL certificates automatically (self-signed or Let's Encrypt) via the acme container.
• docker-compose.no-ssl.yml — for servers behind an external reverse proxy (Traefik, Nginx Proxy Manager, Caddy, etc.) that terminates SSL. The web container only listens on plain HTTP.

Arcane applies changes of the Compose file to a running project on its own. Redeploy After Sync would also start a stopped project, including right after the first sync, before any environment variables exist. Leave it off.

Step 3 – Environment Variables

After adding the sync, open the newly created project. It is still stopped, and Arcane has created an empty .env for it. Copy the content of .env.dist into this .env and adjust it:

• Delete the COMPOSE_FILE line. Arcane evaluates this variable, and the line refers to docker-compose.override.yml, which does not exist in an Arcane project. The Compose file is already selected in the Git sync.
• Replace every placeholder in angle brackets (<pw>, <secret>, …). Generate the passwords and the secret randomly, e.g. with openssl rand -hex 20 and openssl rand -base64 32.
• Enter the value of MARIADB_PASSWORD in place of db_password in DATABASE_URL.
• Set HOST_NAME, RELYING_PARTY_ID, LOCALE and the SSL settings (SELF_SIGNED, LETSENCRYPT, …) for your server.

The variables are described in the Portainer guide and on the Configuration page.

Important: Complete the .env before the first deployment. The database and the SSL certificate are created from these values on the first start. Changing the database passwords afterwards does not change an existing database.

Step 4 – Start

Start the project with Up (German interface: Hoch). Arcane pulls the images and starts all containers. The acme container creates the SSL certificate on the first start.

If a required variable is missing, the deployment fails with required variable ... is missing a value and no container is started. Add the variable and deploy again.

The one-shot container uploads-migration exits after it is done, so Arcane shows the project as partially running — this is expected.

Initialize the Application

Once the php container is reported as healthy, the application must be initialized once. This creates the first admin user and loads the required base data.

1. Open the php container of the project (e.g. fewohbee-php-1) and start a shell in it.

2. Run:

   php bin/console app:first-run

   Arcane opens the shell as www-data, the user the application runs as. Follow the interactive prompts to create the first admin user.

3. Open the application in your browser: https://<HOST_NAME>

If SELF_SIGNED=true is set, your browser will show a security warning on first visit. Accept it to proceed to the login page.

Updates

• Compose files: With Auto Sync, Arcane fetches changes from the repository and applies them to the running project.
• Images: With FEWOHBEE_VERSION=latest, new releases are published under the same tag. Enable Image Update Watcher and Auto Update under Environments → (your environment) → Automations → Updates, or update manually with Redeploy on the project.
• New variables: update-docker.sh is not used with Arcane. When a release introduces new variables, compare your .env with .env.dist. Optional variables have defaults; a missing required variable stops the deployment with the message above.

Backups

Database: Create the read-only backup user (MYSQL_BACKUP_USER) once in a shell of the db container, with the command from the Portainer guide. Arcane cannot run commands in a container on a schedule, so set up the dump as a cron job on the Docker host as described in the Portainer guide. The database container is named after the project, e.g. fewohbee-db-1.

Uploaded images and fonts: They are stored in the volumes uploads-export, uploads-roomcat and uploads-fonts (prefixed with the project name, e.g. fewohbee_uploads-export). Back them up with the Backups tab of each volume in Arcane, which can also store backups on S3 on a schedule. Alternatively, use a cron job on the Docker host as described in the Portainer guide.

Do not back up the volume db-vol while the database is running: a copy of the database files taken during operation can be inconsistent. Use the dumps instead.

Troubleshooting

The first start happened with incomplete variables

With incomplete variables, the database can be initialized with wrong credentials and the acme container can store a placeholder certificate. Neither is recreated later, so correcting the .env alone does not help. The current Compose files refuse to start without the required variables, but this can still happen if placeholders such as <pw> were left in the .env.

On a fresh installation without data, stop the project, delete the volumes db-vol and certs-vol of the project under Volumes, and deploy again.

Deleting db-vol deletes the database. Never do this on an installation that is already in use.