View all installation options
<h1>Rolling Deployer for Docker Compose Services</h1>
<h2>Project Brief</h2>
<p>This project provides a robust deployer for Docker Compose services that use volume mounts. It enables rolling upgrades and safe rollbacks of containerized applications by versioning configuration directories and updating the docker-compose volume source. The deployer requires a <code>docker-compose.yml</code> file for your service, and manages config updates by switching the mounted config directory to the desired version.</p>
<ul>
<li><strong>Rolling upgrades</strong>: Deploy a new config version by specifying a git tag; the deployer clones the config repo at that tag, updates the compose volume, and restarts the service with zero downtime.</li>
<li><strong>Rollbacks</strong>: Instantly revert to a previous config version by specifying an older tag; the deployer switches the config mount and restarts the service.</li>
<li><strong>Requirements</strong>: You must have a valid <code>docker-compose.yml</code> file for your project. The deployer updates the config volume in this file.</li>
</ul>
<h2>Usage</h2>
<h3>With CLI arguments only</h3>
<pre style="background-color:#263238;"><span style="color:#82aaff;">deployer</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">tag</span><span style="color:#82aaff;"> v1.2.3</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">name</span><span style="color:#82aaff;"> my-project </span><span style="color:#89ddff;">\
</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">repo-url</span><span style="color:#82aaff;"> https://github.com/org/repo.git </span><span style="color:#89ddff;">\
</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">mount-path</span><span style="color:#82aaff;"> /etc/myapp/config </span><span style="color:#89ddff;">\
</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">clone-path</span><span style="color:#82aaff;"> /opt/configs </span><span style="color:#89ddff;">\
</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">compose-file</span><span style="color:#82aaff;"> ./docker-compose.yml
</span></pre>
<h3>With .env file integration</h3>
<p>You can provide configuration via a <code>.env</code> file (default: <code>.env</code>). CLI flags always override <code>.env</code> values.</p>
<p>Example <code>.env</code>:</p>
<pre style="background-color:#263238;"><span style="color:#eeffff;">REPO_URL</span><span style="color:#89ddff;">=</span><span style="color:#c3e88d;">https://github.com/org/repo.git
</span><span style="color:#eeffff;">CLONE_PATH</span><span style="color:#89ddff;">=</span><span style="color:#c3e88d;">/opt/configs
</span><span style="color:#eeffff;">MOUNT_PATH</span><span style="color:#89ddff;">=</span><span style="color:#c3e88d;">/etc/myapp/config
</span><span style="color:#eeffff;">COMPOSE_FILE</span><span style="color:#89ddff;">=</span><span style="color:#c3e88d;">./docker-compose.yml
</span><span style="color:#eeffff;">NAME</span><span style="color:#89ddff;">=</span><span style="color:#c3e88d;">my-project
</span><span style="color:#eeffff;">SOCKET_PATH</span><span style="color:#89ddff;">=</span><span style="color:#c3e88d;">/var/run/docker.sock
</span></pre>
<p>Then run:</p>
<pre style="background-color:#263238;"><span style="color:#82aaff;">deployer</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">tag</span><span style="color:#82aaff;"> v1.2.3
</span></pre>
<p>Or override any value:</p>
<pre style="background-color:#263238;"><span style="color:#82aaff;">deployer</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">tag</span><span style="color:#82aaff;"> v1.2.3</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">name</span><span style="color:#82aaff;"> another-project
</span></pre>
<h2>How Rollbacks and Upgrades Work</h2>
<ul>
<li><strong>Upgrade</strong>: The deployer clones the config repo at the specified tag into a versioned directory, updates the docker-compose volume to point to this directory, and runs <code>docker compose up -d --force-recreate</code> for the service.</li>
<li><strong>Rollback</strong>: Specify an older tag to revert; the deployer switches the config mount to the previous version and restarts the service.</li>
<li><strong>Cleanup</strong>: Old config directories are automatically cleaned up (keeping the last 3 versions).</li>
</ul>
<h2>Development</h2>
<p>Release a new version:</p>
<pre style="background-color:#263238;"><span style="color:#82aaff;">git ci</span><span style="color:#89ddff;"> -</span><span style="color:#f78c6c;">am </span><span style="color:#89ddff;">"</span><span style="color:#c3e88d;">Updated version</span><span style="color:#89ddff;">"; </span><span style="color:#82aaff;">cargo release patch</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">execute</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">all</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">no-confirm</span><span style="color:#89ddff;">; </span><span style="color:#82aaff;">git push origin HEAD</span><span style="color:#89ddff;">; </span><span style="color:#82aaff;">git push</span><span style="color:#89ddff;"> --</span><span style="color:#f78c6c;">tags
</span></pre>