IPv4 & IPv6 Leasing - Any RIR, Any LocationOrder Now
Hostperl

Docker Compose Blue-Green Deployments on FreeBSD

By Raman Kumar

Share:

Updated on Nov 16, 2026

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.10

If 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.10

On the VPS as root, confirm the operating system before you do anything else.

freebsd-version

Then confirm the release details and architecture.

uname -a

Successful 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/sh

This 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 deploy

Now create the SSH directory and tighten permissions.

install -d -m 700 -o deploy -g deploy /home/deploy/.ssh

Copy 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
EOF

Then lock the file down.

chown deploy:deploy /home/deploy/.ssh/authorized_keys
chmod 600 /home/deploy/.ssh/authorized_keys

Test the new account from a second terminal on your local computer.

ssh deploy@203.0.113.10

After you log in, confirm that you are the correct user.

whoami
pwd

You 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 update

Install Docker and Compose support from the FreeBSD packages collection.

pkg install -y docker docker-compose

Enable Docker at boot and start it now.

sysrc docker_enable=YES
service docker start

Check that the daemon is running.

service docker status

Then confirm the version.

docker version
/usr/local/bin/docker-compose version

For 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/shared

Now 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
EOF

Create 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

EOF

Repeat 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

EOF

Check ownership and paths.

ls -ld /opt/myapp /opt/myapp/releases/blue /opt/myapp/releases/green

You 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 -d

Then start the green release in its own directory without touching traffic yet.

cd /opt/myapp/releases/green
docker-compose up -d

Verify both containers are running.

docker ps

Inspect 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-web

6) 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
EOF

Replace em0 with your actual public interface if needed. Check interfaces with ifconfig before loading the rule set.

ifconfig

Validate and enable pf.

pfctl -nf /etc/pf.conf
sysrc pf_enable=YES
service pf restart

After the reload, confirm pf is active.

service pf status
pfctl -sr

At 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 -d

Check 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 restart

Now 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.sh

This 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
reboot

After the server returns, connect again and check status.

ssh root@203.0.113.10

Then verify Docker, containers, and pf.

service docker status
docker ps
service pf status

You 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-web

Look 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
ifconfig

If 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 config

The 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.