Docker Compose Blue-Green Deployments on FreeBSD

Why blue-green on FreeBSD works well for hosted apps
If you need Docker Compose blue-green deployments on FreeBSD, the cleanest approach is to run two app stacks side by side, test the new one on a second port, and switch traffic only after health checks pass. That gives you a straightforward rollback path, which matters when a customer launch, payment flow, or API release cannot afford guesswork.
This tutorial uses FreeBSD because it is the least-covered OS track in the current rotation, and it fits neatly with jails, pf, and FreeBSD service control. It also suits Hostperl customers who want predictable release control on a VPS or dedicated server. If you are planning a production deployment, a Hostperl VPS is the right size for most smaller stacks, while a dedicated server hosting plan makes sense when you need more I/O headroom or more concurrent containers.
What you will build
You will set up two Docker Compose releases, blue and green, on a fresh FreeBSD server. One release stays live while the other is updated, smoke-tested, and promoted through a local reverse-proxy port switch. The same pattern works for Node.js apps, Python APIs, small internal tools, and customer-facing SaaS front ends.
- SSH access from a local machine
- FreeBSD version detection
- Docker and Compose installation
- A non-root deploy account
- Two Compose stacks with separate ports
- PF rules for controlled public access
- Health checks, logs, rollback, and reboot persistence
For deployment planning and release control, the same operational ideas also fit the rollback patterns in Docker deployment rollbacks for safer releases in 2026. If your app talks to PostgreSQL, pair this with PostgreSQL read replicas for safer scaling in 2026 so your database layer does not become the bottleneck during cutover.
1) Connect to the server and confirm FreeBSD
On your local computer, connect to the server with the documentation IP shown below. Replace 203.0.113.10 with your real public server IP from Hostperl.
ssh root@203.0.113.10If your Hostperl setup uses a default non-root account, connect with that account instead, still replacing the IP with your real server address. Keep the original root session open until the new login is verified later.
ssh deploy@203.0.113.10On the VPS as root, confirm the operating system before you do anything else.
freebsd-versionThen confirm the release details and architecture.
uname -aSuccessful output should show a FreeBSD 13.x or 14.x release line and the host name. If you see a different system, stop and use the correct platform guide.
2) Create a non-root deploy user
Run this as root so your release work happens from a limited account instead of the superuser shell.
pw useradd -n deploy -m -s /bin/shThis creates the deploy account and home directory. Set a password only if you need password login for initial access; in most hosted environments, SSH keys are safer.
passwd deployNow create the SSH directory and tighten permissions.
install -d -m 700 -o deploy -g deploy /home/deploy/.sshCopy your public key into place. Replace the key string with your own public key from your local computer.
cat > /home/deploy/.ssh/authorized_keys <<'EOF'
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMyExampleKeyForDocumentationOnly hostperl-deploy
EOFThen lock the file down.
chown deploy:deploy /home/deploy/.ssh/authorized_keys
chmod 600 /home/deploy/.ssh/authorized_keysTest the new account from a second terminal on your local computer.
ssh deploy@203.0.113.10After you log in, confirm that you are the correct user.
whoami
pwdYou should see deploy and /home/deploy. If that works, keep this session open and return to your root session for the software setup.
3) Install Docker and the Compose plugin on FreeBSD
On the VPS as root, update packages first.
pkg updateInstall Docker and Compose support from the FreeBSD packages collection.
pkg install -y docker docker-composeEnable Docker at boot and start it now.
sysrc docker_enable=YES
service docker startCheck that the daemon is running.
service docker statusThen confirm the version.
docker version
/usr/local/bin/docker-compose versionFor production work on Hostperl VPS or dedicated server environments, this is the point where you should decide whether the app belongs on a single VPS or on a larger box with more memory. The more concurrent containers you run, the more useful a dedicated server becomes.
4) Prepare the deployment directory and sample app
On the VPS as the non-root sudo user, create the app directory and a release folder layout. FreeBSD does not use Linux-style sudo groups by default, so this tutorial keeps the app deployment simple and uses root only where needed.
su - deploy
mkdir -p /opt/myapp/releases/blue
mkdir -p /opt/myapp/releases/green
mkdir -p /opt/myapp/sharedNow create a minimal app image and Compose file for the blue release. This example runs a small Nginx container that serves a release marker page, which makes cutover verification easy.
cat > /opt/myapp/releases/blue/docker-compose.yml <<'EOF'
services:
web:
image: nginx:1.27-alpine
container_name: myapp-blue-web
ports:
- "8081:80"
volumes:
- ./html:/usr/share/nginx/html:ro
restart: unless-stopped
EOFCreate the blue release content.
mkdir -p /opt/myapp/releases/blue/html
cat > /opt/myapp/releases/blue/html/index.html <<'EOF'
myapp blue release
Release: blue
EOFRepeat the same for green.
cat > /opt/myapp/releases/green/docker-compose.yml <<'EOF'
services:
web:
image: nginx:1.27-alpine
container_name: myapp-green-web
ports:
- "8082:80"
volumes:
- ./html:/usr/share/nginx/html:ro
restart: unless-stopped
EOF
mkdir -p /opt/myapp/releases/green/html
cat > /opt/myapp/releases/green/html/index.html <<'EOF'
myapp green release
Release: green
EOFCheck ownership and paths.
ls -ld /opt/myapp /opt/myapp/releases/blue /opt/myapp/releases/greenYou should see the deploy user own the directories if you created them from that account. If not, fix ownership with chown -R deploy:deploy /opt/myapp.
5) Start blue and green side by side
Bring up the blue release first so it becomes the current live version.
cd /opt/myapp/releases/blue
docker-compose up -dThen start the green release in its own directory without touching traffic yet.
cd /opt/myapp/releases/green
docker-compose up -dVerify both containers are running.
docker psInspect the blue and green ports locally on the server.
fetch -o - http://127.0.0.1:8081/
fetch -o - http://127.0.0.1:8082/You should see the blue and green release marker pages. If either one fails, use the logs command below before you go any further.
docker logs myapp-blue-web
docker logs myapp-green-web6) Add pf rules for controlled public access
FreeBSD usually ships with pf available, and it is the right place to control which app port receives public traffic. The idea is simple: keep the current release on a private port, and only expose the active port you actually want users to reach.
On the VPS as root, create a minimal rules file that allows SSH and the active app port. This example exposes port 8081 first for the blue release.
cat > /etc/pf.conf <<'EOF'
set skip on lo
pass in on em0 proto tcp from any to any port 22 keep state
pass in on em0 proto tcp from any to any port 8081 keep state
block in all
EOFReplace em0 with your actual public interface if needed. Check interfaces with ifconfig before loading the rule set.
ifconfigValidate and enable pf.
pfctl -nf /etc/pf.conf
sysrc pf_enable=YES
service pf restartAfter the reload, confirm pf is active.
service pf status
pfctl -srAt this point, you should be able to reach the blue release from a client browser or curl session. The green release stays private until cutover.
7) Test the app from a client before cutover
On your local computer, confirm that the live port returns the blue release page. Replace the example IP with your own server IP if it differs.
curl -i http://203.0.113.10:8081/You should receive an HTTP 200 response and the text Release: blue. If this fails, the common causes are a wrong PF interface, a stopped container, or a host firewall rule that blocks the port.
8) Promote the green release with a safe rollback path
To promote green, keep blue running until you have confirmed green is healthy on its private port. That gives you a backout path if the new release is bad.
First, update the green content or image. In this example, we only change the marker page so you can see the workflow. In a real app, you would update the image tag, app code, or environment file, then rebuild the stack.
cd /opt/myapp/releases/green
cat > html/index.html <<'EOF'
myapp green release
Release: green is now ready
EOF
docker-compose up -dCheck the green release again.
fetch -o - http://127.0.0.1:8082/If that looks right, change pf so public traffic goes to green instead of blue. Edit the rule file and test syntax before reloading it.
cat > /etc/pf.conf <<'EOF'
set skip on lo
pass in on em0 proto tcp from any to any port 22 keep state
pass in on em0 proto tcp from any to any port 8082 keep state
block in all
EOF
pfctl -nf /etc/pf.conf
service pf restartNow the active release is green. Verify from the local server first, then from your client.
fetch -o - http://127.0.0.1:8082/
curl -i http://203.0.113.10:8082/If you need to roll back, switch the PF rule back to port 8081, validate syntax again, and reload. Blue will become live immediately without stopping either container.
9) Add a simple rollback script
A written rollback path keeps incident handling calmer. Save a small script in the deployment directory so the on-call person can reverse the cutover without editing the whole stack by hand.
cat > /opt/myapp/rollback-to-blue.sh <<'EOF'
#!/bin/sh
set -eu
cat > /etc/pf.conf <<'EOR'
set skip on lo
pass in on em0 proto tcp from any to any port 22 keep state
pass in on em0 proto tcp from any to any port 8081 keep state
block in all
EOR
pfctl -nf /etc/pf.conf
service pf reload
EOF
chmod 700 /opt/myapp/rollback-to-blue.shThis script only changes the exposed port. It does not destroy either container or remove any release files, which is exactly what you want during an incident.
10) Verify reboot persistence
Restart the server only after you have confirmed the containers and pf rules are persistent enough for your release plan. Docker was enabled earlier, so the daemon should come back after a reboot. The containers themselves use restart: unless-stopped, which is the piece that brings them back automatically.
On the VPS as root, confirm the service settings and then reboot during a maintenance window.
sysrc docker_enable
sysrc pf_enable
rebootAfter the server returns, connect again and check status.
ssh root@203.0.113.10Then verify Docker, containers, and pf.
service docker status
docker ps
service pf statusYou should see both containers restored and pf still active. If the containers do not return, inspect docker logs and confirm the compose directories still exist.
11) Troubleshooting the most common failures
Container does not start
docker ps -a
docker logs myapp-blue-webLook for port conflicts or a missing compose file. The usual fix is to correct the port mapping or rebuild the release directory, then run docker-compose up -d again.
Public traffic does not reach the app
pfctl -sr
ifconfigIf the interface name is wrong, replace em0 in /etc/pf.conf with the correct interface, run pfctl -nf /etc/pf.conf, then reload pf.
Compose changes do not apply
cd /opt/myapp/releases/green
docker-compose configThe config output should render the final Compose file. If it fails, fix YAML indentation or a bad image name before restarting the stack.
Rollback was needed during release
/opt/myapp/rollback-to-blue.sh
curl -i http://203.0.113.10:8081/If blue responds again, the rollback succeeded and you can investigate the failed green release separately.
If you want a release workflow like this running on infrastructure that you can actually grow with, Hostperl VPS and dedicated server options are a practical place to start. A Hostperl VPS works well for smaller container stacks, while dedicated server hosting gives you more room for higher traffic, more images, and faster recovery.
Hostperl customers often use this pattern for agency launches, internal tools, and customer portals where rollback speed matters more than theory.
FAQ
Can I use this pattern for a real web app instead of a test page?
Yes. Replace the sample Nginx container with your app image, keep the two ports separate, and test the new release before exposing it publicly.
Why use FreeBSD for Docker Compose deployments?
FreeBSD gives you predictable service control, pf firewalling, and good operational separation. It fits teams that already manage FreeBSD jails or FreeBSD-based infrastructure.
What is the safest rollback method?
Keep the old release running, switch the firewall rule back to its port, and validate the old path before stopping the failed release.
Do I need a reverse proxy for this to work?
No. This tutorial uses firewall-based port switching to keep the workflow simple. You can add Nginx or another proxy later if your app needs TLS termination or path routing.
Should I use this on a VPS or a dedicated server?
Use a VPS for small to medium container workloads. Move to a dedicated server when memory pressure, storage I/O, or multiple services make the smaller plan too tight.
