Remote profiles and code preview

ContaoDock works with existing servers; it does not create hosting accounts or provision machines. A Staging or Production profile identifies a host, SSH port, user, remote project path, web root, optional public site URL, and optional key path.

Configure a profile

1. Open a project’s Environment settings.
2. Enter the host, SSH port, username, deployment root, and web root (public or web). Add the public site URL if you want an HTTP readiness probe after deployment or promotion.
3. Use the SSH agent or select a private key path.
4. Make sure the server host key is trusted by OpenSSH.
5. Save the profile and run the connection check.

The check uses OpenSSH to validate access and report whether the deployment root is writable, PHP CLI and tar are installed, symlinks work, and shared/.env plus shared/files/ exist. A failed check blocks deployment. ContaoDock shows the failed prerequisite in red and includes a link to this guide. The check only creates and immediately removes a temporary symlink probe; it does not upload application code or change the active release.

Review the transfer preview

The preview reports source revision and working-tree status when available, included paths, excluded paths, and exclusion counts. Environment files, credentials, local runtime state, caches, and user uploads are excluded. A dirty working tree deploys its current files on disk after an explicit confirmation.

Prepare the Staging host for code deployment

The first Staging deployment flow uses versioned releases. Before deploying, configure the web server’s document root to:

<deployment-root>/current/<web-root>

ContaoDock runs its deployment commands over SSH on the remote host. The configured deployment root must exist, and the SSH user must be able to create release folders and symlinks there. The host also needs a PHP CLI version compatible with the site and tar. PHP installed only inside a Docker container does not satisfy the current check: deployment does not yet run commands through docker exec.

Create these shared paths under the deployment root and put the Staging environment configuration and persistent uploads there:

shared/.env
shared/files/

For example, on a Debian or Ubuntu host, replace deploy, www-data, and the path with the SSH user, the actual web-server group, and a directory on the remote host. Keep Staging and Production roots separate.

sudo install -d -o deploy -g www-data -m 2775 /srv/contao/staging
sudo install -d -o deploy -g www-data -m 2775 /srv/contao/staging/shared/files

Prepare a Staging-specific .env containing the database connection and application settings for Staging. Do not copy Production credentials into Staging. Transfer it through your hosting provider’s secure file manager or another secure channel, then set ownership and permissions so the SSH user can deploy and the PHP/web-server user can read it. Do not commit this file to Git. For an existing Staging site, preserve its current uploads by copying them into shared/files/; for a new empty site, an empty directory is fine.

The following table maps every failed check to a fix:

Check	How to resolve it
Deployment root	Set the profile’s Deployment root to the intended server directory. Create it and grant the SSH user write permission. The web-server/PHP user must be able to read deployed files. Avoid broad chmod 777; use the hosting provider’s recommended owner/group or ACL setup.
PHP CLI	Install or enable the command-line PHP package on the SSH host, using a version compatible with the site’s PHP runtime. Confirm php --version works for the same SSH user ContaoDock uses. PHP available only inside a container is not supported by this deployment flow yet.
tar	Install the host’s tar package and confirm tar --version works for the SSH user.
Shared environment file	Put a valid Staging .env at <deployment-root>/shared/.env. The file must contain the Staging database connection and required Contao app settings; an empty file only clears the existence check and will not make the site run.
Shared uploads directory	Create <deployment-root>/shared/files/. If the Staging site already has uploads, copy them there before switching its document root.
Release directory layout	current must be absent for a first deployment or be a symlink to a previous ContaoDock release. If it is a real directory, back it up and plan a migration before changing it; do not delete a live site to clear this check.
Symlink support	The filesystem and hosting plan must allow the SSH user to create symlinks in the deployment root. Ask the host to enable symlinks or choose a supported directory.

After applying changes, return to Environment → Staging, choose Save & test connection, and resolve any remaining red checks. Then go to Overview → Review & deploy. ContaoDock reruns the checks when preparing the deployment.

The current development build creates releases/, extracts each code-only archive into a new release, keeps the exact .tar.gz artifact alongside it, links .env and files/ from shared/, clears the Contao production cache, and atomically replaces the current symlink only after the new release is ready. The server needs SSH access, tar, PHP CLI, a writable release root, and symlink support. The profile check also reports whether the shared paths and current layout are ready. The local project must have composer.json, composer.lock, and vendor/autoload.php; dependencies are packaged locally, and remote Composer is not run. After a successful SSH check, each environment card reads the active release ID from that symlink and offers a manual refresh. When a public site URL is configured, ContaoDock requests it with curl after activation, follows HTTP redirects, and records the response code or error in deployment history. A failed probe does not undo the release switch; it reports the health-check failure while keeping the activated release visible. Leave the URL blank to skip the probe. The published 0.1.0 DMG predates this deployment feature.

After both server profiles are configured, open Overview. Choose Review & deploy in step 1, inspect the included/excluded paths and working-tree status, then choose Deploy to Staging. ContaoDock rechecks remote requirements before upload and shows any missing server setup in the review. The previous release remains active if upload or cache clearing fails. ContaoDock records the release ID, source revision, working-tree state, target, and SHA-256 in its local project registry. After checking the Staging site, choose Promote this release in step 2 of Overview to fetch the archived Staging artifact, verify the checksum, and deploy that exact release to a separate Production root. Overview also offers a rollback to a previous Production release when one is available. Code promotion and rollback do not synchronize databases or uploaded files. Keep both release directories and their .tar.gz artifacts on disk; automatic pruning is not implemented.

Deployment and HTTP checks have not been verified against a representative remote host. Do not point Staging and Production profiles at the same deployment root.

Release retention

The Environment tab can preview remote release cleanup for Staging or Production. Choose to keep the newest 3, 5, 10, or 20 recognized releases. ContaoDock always protects the active release and only lists release directories that include Composer’s autoloader and the corresponding archived artifact. Review the deletion list and confirm before cleanup; the app rechecks the remote list and current symlink before deleting. Cleanup permanently removes inactive release directories and their .tar.gz archives, so pruned Staging releases can no longer be promoted and pruned Production releases can no longer be rolled back. No automatic pruning is performed.