That sounds simple until you ask for BUN_VERSION=latest and your deployment fails before your app even gets a chance to embarrass itself.

As of July 6, 2026, the latest Bun release is 1.3.14, while Cloudflare Pages still defaults to Bun 1.2.15. After a few rounds of testing, the most reliable fix I found is to skip Cloudflare's automatic dependency install, install Bun through npm with scripts enabled, and force the build shell to use npm's global binary path before Cloudflare's preinstalled Bun.

1. What goes wrong with BUN_VERSION=latest

Cloudflare's documented path is to set BUN_VERSION in your Pages project. For the default preinstalled version, that can be fine. For latest or any other specific version, it can fail during Bun installation with a 403 from the installer path:

2026-07-06T01:18:13.088163Z	Installing bun latest
2026-07-06T01:18:13.34936Z	Plugin bun's list-all callback script failed with output:
2026-07-06T01:18:13.351082Z	curl: (22) The requested URL returned error: 403
2026-07-06T01:18:13.353396Z
2026-07-06T01:18:13.365851Z	bun  is already installed
2026-07-06T01:18:13.61882Z	Plugin bun's list-all callback script failed with output:
2026-07-06T01:18:13.619964Z	curl: (22) The requested URL returned error: 403
2026-07-06T01:18:13.622207Z
2026-07-06T01:18:13.63001Z	Error: Exit with error code: 1
2026-07-06T01:18:13.630373Z	    at ChildProcess.<anonymous> (/snapshot/dist/run-build.js)
2026-07-06T01:18:13.630738Z	    at Object.onceWrapper (node:events:652:26)
2026-07-06T01:18:13.630897Z	    at ChildProcess.emit (node:events:537:28)
2026-07-06T01:18:13.63146Z	    at ChildProcess._handle.onexit (node:internal/child_process:291:12)
2026-07-06T01:18:13.638586Z	Failed: build command exited with code: 1
2026-07-06T01:18:14.841415Z	Failed: error occurred while running build command

This is not a brand-new paper cut. Related reports have been around for years, including oven-sh/setup-bun#70 and oven-sh/bun#6305. The short version: the install flow can trip over a remote download or rate limit problem, and Cloudflare Pages treats that as a failed build. Fair enough, but not very helpful when all you wanted was bun install. The funny part is that this is not Cloudflare rate-limiting Bun. It is Bun's own download side saying no, while bun.sh and bun.com currently return server: cloudflare. Infrastructure irony, served with a 403.

I also checked the current installer script. On Linux, it is refreshingly boring: detect the platform and CPU, pick a target such as linux-x64, linux-x64-baseline, linux-aarch64, or a musl build for Alpine, then download https://github.com/oven-sh/bun/releases/latest/download/bun-$target.zip, unzip it into $BUN_INSTALL/bin or ~/.bun/bin, and mark the binary executable. If bun is not already on PATH, it writes the usual BUN_INSTALL and PATH lines into the user's shell config when it can, or prints the commands to add manually. There is no package index, dependency solver, or anything especially magical here. It is mostly a small shell script pointing at GitHub Release assets, which makes the rate limit feel even stranger.

2. Why npm install -g bun alone is not enough

There is a common workaround: skip automatic dependency installation and run Bun yourself. For example, dt.in.th documented this pattern:

npm install -g bun && bun install && bun run build

That gets close, but in my Cloudflare Pages tests it still used Cloudflare's older preinstalled Bun. The build log told on it:

2026-07-06T19:40:16.361085Z	Executing user command: npm install -g bun && bun install && bun run build
2026-07-06T19:40:33.293457Z
2026-07-06T19:40:33.30093Z	added 5 packages in 16s
2026-07-06T19:40:33.301321Z	npm warn allow-scripts 1 package has install scripts not yet covered by allowScripts:
2026-07-06T19:40:33.301456Z	npm warn allow-scripts   bun@1.3.14 (postinstall: node install.js)
2026-07-06T19:40:33.301535Z	npm warn allow-scripts
2026-07-06T19:40:33.301612Z	npm warn allow-scripts Run `npm approve-scripts --allow-scripts-pending` to review, or `npm approve-scripts <pkg>` to allow.
2026-07-06T19:40:33.966013Z	Reshimming asdf nodejs...
2026-07-06T19:40:43.03495Z	bun install v1.2.15 (df017990)

Two things happened there:

1. npm installed the bun package, but its install script needed to be allowed.
2. The shell still resolved bun to Cloudflare's preinstalled/asdf-shimmed Bun before the npm-installed binary.

The result is the worst kind of failure: it looks like you installed the new Bun, then the build quietly uses the old one. Very considerate. Also very wrong.

3. The working Cloudflare Pages setup

First, disable automatic dependency installation so Cloudflare Pages does not run its own package manager step before your command.

In the Cloudflare Dashboard:

1. Go to Build > Compute > Workers & Pages
2. Open your Pages project
3. Go to Settings > Variables and secrets
4. Add this build variable:

Type: Text

Variable name:

SKIP_DEPENDENCY_INSTALL

Value:

true

or

1

Cloudflare documents this variable in its build image guide: it disables automatic dependency installation so you can run a custom install command.

Then set your Pages build command to this:

npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build

Screenshot:

Here is what each part does:

1. npm install -g --allow-scripts=bun bun

   Installs Bun from npm and allows Bun's install script to run. Without that script, you can end up with the wrapper package but not the native Bun binary you actually need.

2. export PATH="$(npm prefix -g)/bin:$PATH"

   Puts npm's global binary directory at the front of PATH. This is the important bit. It makes the next bun command resolve to the npm-installed Bun instead of Cloudflare's default Bun 1.2.15.

3. bun --version

   Prints the Bun version in the build log. This is not decoration. It is the smoke alarm. If this does not print the version you expect, stop reading the rest of the log like it owes you money and fix the PATH first.

4. bun install && bun run build

   Installs dependencies and runs your normal build with the Bun binary you just verified.

4. What a good build log looks like

With the command above, the build finally used Bun 1.3.14:

2026-07-06T19:57:20.330572Z	SKIP_DEPENDENCY_INSTALL is present in environment. Skipping automatic dependency installation.
2026-07-06T19:57:20.330827Z	Executing user command: npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build
2026-07-06T19:57:26.270869Z	added 5 packages in 5s
2026-07-06T19:57:26.853104Z	Reshimming asdf nodejs...
2026-07-06T19:57:29.865184Z	1.3.14
2026-07-06T19:57:29.870732Z	bun install v1.3.14 (0d9b296a)
2026-07-06T19:58:07.304997Z	Success! Uploaded 38 files (2604 already uploaded) (1.85 sec)
2026-07-06T19:58:12.958621Z	Success: Assets published!
2026-07-06T19:58:13.849805Z	Success: Your site was deployed!

The key lines are:

1.3.14
bun install v1.3.14 (0d9b296a)

That proves both bun --version and bun install are using the same current Bun binary.

5. Should you use latest or pin a version?

For a personal site or a small project, installing the latest Bun during the Pages build may be convenient. You get current fixes without editing the Cloudflare project every time Bun ships.

For production builds where repeatability matters, pin the npm package instead:

npm install -g --allow-scripts=bun bun@1.3.14 && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build

That keeps the same PATH fix, but removes surprise upgrades from the equation. Surprise upgrades are fun in exactly one place: other people's staging environments.

6. Final checklist

Use this setup when you want Cloudflare Pages to build with the current Bun instead of the preinstalled default:

1. Add SKIP_DEPENDENCY_INSTALL=true in Pages variables and secrets.

2. Use this build command:

   npm install -g --allow-scripts=bun bun && export PATH="$(npm prefix -g)/bin:$PATH" && bun --version && bun install && bun run build
   

3. Check the build log for the expected version after bun --version.

4. Check that bun install reports the same version.

If Bun or Cloudflare fixes the issue later, this workaround can become shorter. Bun can fix the rate limit behavior on its own download side. Cloudflare can also avoid Bun's installer script for a managed build runtime and fetch the versioned or latest GitHub Release asset directly. Neither option requires a new theory of computing. Until then, the build command above gives you the latest Bun without asking Cloudflare's preinstalled runtime to kindly stop standing in the doorway.

Updated July 6, 2026: PHP 8.5 and MariaDB 12.3 LTS.

Introduction

When Debian prepares a new stable release, it uses a freeze policy. Package versions are locked near release time, and they usually stay on that major version for the life of the release. Some packages get newer builds through Debian backports, but many do not.

That is fine for a lot of servers. For web apps that care about newer Nginx, MariaDB, or PHP features, it can be annoying. This guide uses trusted third-party repositories for those components while keeping the rest of the system on Debian or Ubuntu packages.

1. Prerequisites

Use Debian Stable or oldstable. Debian sid is not supported here. On Ubuntu, use an Ubuntu LTS release rather than an interim release.

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands.

Update the system and install the tools needed to add APT repositories:

sudo apt update -y
sudo apt upgrade -y
sudo apt full-upgrade -y
sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates -y

2. Install Nginx

N.WTF syncs official Nginx source and packaging, then builds it with a current OpenSSL version.

2.1 Add GPG key

curl -sS https://n.wtf/public.key | sudo gpg --dearmor -o /usr/share/keyrings/n.wtf.gpg

2.2 Add repository

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror-cdn.xtom.com/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

On Debian, extrepo can add the same repository:

sudo apt install extrepo -y
sudo extrepo enable n.wtf

2.3 Update system and install Nginx

sudo apt update
sudo apt install nginx-extras -y

Check that Nginx was installed:

root@debian ~ # nginx -v
nginx version: nginx-n.wtf/1.31.2

3. Install PHP

Use PHP packages from Ondřej Surý, who maintains widely used PHP builds for Debian and Ubuntu.

3.1 Add GPG key and repository

Debian:

sudo wget -O /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list

On Debian, you can use extrepo instead:

sudo extrepo enable sury

On Ubuntu, use Ondřej Surý's PPA:

sudo add-apt-repository ppa:ondrej/php

3.2 Install specific PHP version

Avoid installing broad php-* packages directly. They may pull a PHP version your application does not expect.

After adding the repository, update APT:

sudo apt update

Then install one specific PHP version and the extensions you need. This extension set works for a typical WordPress site:

Install PHP 8.5 (Opcache is enabled by default in PHP 8.5):

sudo apt install php8.5-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,soap,gmp,bcmath} -y

Install PHP 8.4

sudo apt install php8.4-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 8.3

sudo apt install php8.3-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 8.2

sudo apt install php8.2-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

The PHP versions below are EOL and are no longer officially supported.

Install PHP 8.1

sudo apt install php8.1-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 8.0

sudo apt install php8.0-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 7.4

sudo apt install php7.4-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 7.3

sudo apt install php7.3-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 7.2 (mcrypt was deprecated in PHP 7.1 and removed from core in 7.2)

sudo apt install php7.2-{fpm,cli,mysql,curl,gd,mbstring,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 7.1

sudo apt install php7.1-{fpm,cli,mysql,curl,gd,mbstring,mcrypt,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 7.0

sudo apt install php7.0-{fpm,cli,mysql,curl,gd,mbstring,mcrypt,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Install PHP 5.6

sudo apt install php5.6-{fpm,cli,mysql,curl,gd,mbstring,mcrypt,xml,zip,imap,opcache,soap,gmp,bcmath} -y

Search for any other PHP extensions your application needs:

apt search php8.5-*

Next, adjust the matching php.ini file:

• For PHP 8.5, edit /etc/php/8.5/fpm/php.ini.
• For PHP 7.4, edit /etc/php/7.4/fpm/php.ini.
• For another version, change the version number in the path.

For PHP-FPM, disable cgi.fix_pathinfo:

This avoids an old class of path handling problems when Nginx passes requests to PHP-FPM.

sudo sed -i 's/;cgi.fix_pathinfo=1/cgi.fix_pathinfo=0/' /etc/php/8.5/fpm/php.ini 

Adjust upload and post limits:

Change upload_max_filesize and post_max_size if your application needs larger uploads:

sudo sed -i 's/upload_max_filesize = 2M/upload_max_filesize = 10M/' /etc/php/8.5/fpm/php.ini
sudo sed -i 's/post_max_size = 8M/post_max_size = 10M/' /etc/php/8.5/fpm/php.ini

If you install multiple PHP versions, choose the default CLI version with:

sudo update-alternatives --config php

Restart PHP-FPM after editing its configuration:

sudo systemctl restart php8.5-fpm

Now add an Nginx site configuration.

Create a new configuration file for your site under /etc/nginx/sites-available/:

sudo bash -c 'cat > /etc/nginx/sites-available/example.com.conf << EOF
server {
        listen 80;
        listen [::]:80;

# Web root, I recommend using /var/www
        root /var/www/example.com;
        index index.php index.html index.htm;

# Replace example.com with your domain name
        server_name example.com;

        location / {
            try_files \$uri \$uri/ =404;
        }

# Enable PHP 8.5-FPM. For PHP 7.4, use fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        location ~ \.php$ {
            include snippets/fastcgi-php.conf;
            fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        }
}
EOF'

Link it into /etc/nginx/sites-enabled:

sudo ln -s /etc/nginx/sites-available/example.com.conf /etc/nginx/sites-enabled/example.com.conf

Test the configuration and reload Nginx:

sudo nginx -t
sudo nginx -s reload

Create /var/www/example.com and make www-data the owner:

sudo mkdir -p /var/www/example.com
sudo chown www-data:www-data /var/www/example.com -R

Create phpinfo.php to test PHP:

sudo -u www-data bash -c 'cat > /var/www/example.com/phpinfo.php << EOF
<?php phpinfo(); ?>
EOF'

Visit http://example.com/phpinfo.php after the A or AAAA DNS records for example.com point to this server.

4. Install MariaDB

This setup uses MariaDB instead of MySQL for historical and licensing reasons.

4.1 Add GPG key

curl -sSL https://supplychain.mariadb.com/MariaDB-Server-GPG-KEY | sudo gpg --dearmor -o /usr/share/keyrings/mariadb.gpg

4.2 Add repository

Debian:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/mariadb.gpg] https://dlm.mariadb.com/repo/mariadb-server/12.3/repo/debian $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/mariadb.list

Or use extrepo:

sudo extrepo enable mariadb-12.3

Ubuntu:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/mariadb.gpg] https://dlm.mariadb.com/repo/mariadb-server/12.3/repo/ubuntu $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/mariadb.list

4.3 Install MariaDB

sudo apt update
sudo apt install mariadb-server mariadb-client -y

After installing MariaDB, run sudo mariadb-secure-installation if you want to set a root password and apply the usual basic hardening prompts.

4.4 Create database and test

Before creating a database, generate a random password. The openssl command works well:

openssl rand -hex 16

Or

openssl rand -base64 16

Or install pwgen:

sudo apt install pwgen -y
pwgen 16

Log in to MariaDB as root. By default, local root login uses Unix socket authentication, so you do not need a MariaDB root password:

sudo mariadb

Create an example database called example_database:

CREATE DATABASE example_database DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Create an example user example_user and grant permissions:

GRANT ALL ON example_database.* TO 'example_user'@'localhost' IDENTIFIED BY 'Your_Powerful_Strong_Password';
FLUSH PRIVILEGES;

Exit MariaDB:

EXIT;

Create mysql-test.php in /var/www/example.com:

sudo -u www-data tee /var/www/example.com/mysql-test.php > /dev/null << 'EOF'
<?php
$dbname = 'example_database';    //MySQL database
$dbuser = 'example_user';   //MySQL user
$dbpass = 'Your_Powerful_Strong_Password';
$dbhost = 'localhost';  //use localhost if you install locally
$link = mysqli_connect($dbhost, $dbuser, $dbpass) or die("Unable to Connect to '$dbhost'");
mysqli_select_db($link, $dbname) or die("Could not open the db '$dbname'");
$test_query = "SHOW TABLES FROM $dbname";
$result = mysqli_query($link, $test_query);
$tblCnt = 0;
while($tbl = mysqli_fetch_array($result)) {
  $tblCnt++;
  #echo $tbl[0]."<br />\n";
}
if (!$tblCnt) {
  echo "MySQL is working fine. There are no tables.";
} else {
  echo "MySQL is working fine. There are $tblCnt tables.";
}
?>
EOF

The quoted 'EOF' delimiter keeps the shell from touching anything inside, so the PHP lands on disk exactly as written.

Visit http://example.com/mysql-test.php to verify the database connection.

If the page shows MySQL is working fine. There are no tables., PHP can connect to MariaDB.

Once both tests pass, delete the test files. mysql-test.php has your database password in it, and neither belongs on a public web root:

sudo rm /var/www/example.com/phpinfo.php /var/www/example.com/mysql-test.php

What is Ghost?

Ghost is an open-source publishing platform for blogs, newsletters, and paid memberships. It gives you the editor, admin panel, email tooling, and subscription features in one place.

This tutorial runs Ghost on Docker with MySQL, then puts it behind either Nginx or Caddy.

1. Prerequisites

Make sure you have installed Debian Stable (either oldstable or stable releases, sid is not supported) or Ubuntu LTS (Interim releases not supported).

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands.

The docker commands in this guide are not prefixed with sudo: add your user to the docker group (sudo usermod -aG docker $USER, then log out and back in), or prefix the docker commands with sudo yourself.

Install Docker and Docker Compose by following the instructions in this article.

You may need a Mailgun account to send emails and newsletters. You can sign up here.

2. Create a Docker Compose file

Create a file named compose.yaml at /opt/compose.yaml:

cd /opt

echo 'name: ghost

services:
  ghost:
    image: ghost:6-alpine
    container_name: ghost
    restart: always
    ports:
      - 127.0.0.1:2368:2368
    environment:
      TZ: "UTC"
      database__client: mysql
      database__connection__host: ghost_database
      database__connection__user: ghost_user
      database__connection__password: YourRandomMySQLPassword
      database__connection__database: ghost_database
      mail__transport: smtp
      mail__from: "Your Name <noreply@example.com>"
      mail__options__service: Mailgun
      mail__options__host: smtp.mailgun.org
      mail__options__port: 465
      mail__options__auth__user: YourMailgunEmailUsername
      mail__options__auth__pass: YourMailgunEmailPassword
      mail__options__secure: true
      url: https://example.com/
    volumes:
      - ./data/ghost:/var/lib/ghost/content
    networks:
      - ghost-network

  ghost_database:
    image: mysql:8
    container_name: ghost_database
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: YourRandomMySQLRootPassword
      MYSQL_DATABASE: ghost_database
      MYSQL_USER: ghost_user
      MYSQL_PASSWORD: YourRandomMySQLPassword
    volumes:
      - ./data/mysql:/var/lib/mysql
    networks:
      - ghost-network

  watchtower:
    image: nickfedor/watchtower:latest
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_POLL_INTERVAL=86400
    networks:
      - ghost-network

networks:
  ghost-network:
    name: ghost-network
' | sudo tee ./compose.yaml

Replace the Ghost environment settings with your own values.

Pull the images and start the containers:

docker compose pull
docker compose up -d

Use docker ps to check that the containers are running:

# docker ps
CONTAINER ID   IMAGE                          COMMAND                  CREATED         STATUS                            PORTS                      NAMES
bd0cb912685f   ghost:5-alpine                 "docker-entrypoint.s…"   3 seconds ago   Up Less than a second             127.0.0.1:2368->2368/tcp   ghost
eb058d47d520   mysql:lts                      "docker-entrypoint.s…"   3 seconds ago   Up 2 seconds                      3306/tcp, 33060/tcp        ghost_database
b96d0acfb0f9   nickfedor/watchtower:latest     "/watchtower"            3 seconds ago   Up 2 seconds (health: starting)   8080/tcp                   watchtower

Use docker logs ghost if you want to check Ghost's startup logs:

# docker logs ghost
...........
[2025-05-05 19:06:38] INFO Database is in a ready state.
[2025-05-05 19:06:38] INFO Ghost database ready in 5.036s
[2025-05-05 19:06:39] INFO Invalidating assets for regeneration
[2025-05-05 19:06:39] INFO Adding offloaded job to the inline job queue
[2025-05-05 19:06:39] INFO Scheduling job mentions-email-report at 13 33 * * * *. Next run on: Mon May 05 2025 19:33:13 GMT+0000 (Coordinated Universal Time)
[2025-05-05 19:06:39] INFO Adding one-off job to inlineQueue with current length = 0 called 'members-migrations'
[2025-05-05 19:06:39] INFO Stripe not configured - skipping migrations
[2025-05-05 19:06:40] INFO URL Service ready in 1156ms
[2025-05-05 19:06:40] INFO Adding offloaded job to the inline job queue
[2025-05-05 19:06:40] INFO Scheduling job clean-expired-comped at 59 13 3 * * *. Next run on: Tue May 06 2025 03:13:59 GMT+0000 (Coordinated Universal Time)
[2025-05-05 19:06:40] INFO Adding offloaded job to the inline job queue
[2025-05-05 19:06:40] INFO Scheduling job clean-tokens at 35 51 0 * * *. Next run on: Tue May 06 2025 00:51:35 GMT+0000 (Coordinated Universal Time)
[2025-05-05 19:06:40] INFO Ghost booted in 6.953s
[2025-05-05 19:06:40] INFO Adding offloaded job to the inline job queue
[2025-05-05 19:06:40] INFO Scheduling job update-check at 12 0 17 * * *. Next run on: Tue May 06 2025 17:00:12 GMT+0000 (Coordinated Universal Time)
[2025-05-05 19:06:40] INFO Running milestone emails job on Tue May 06 2025 19:06:40 GMT+0000 (Coordinated Universal Time)

Ghost is now listening on 127.0.0.1:2368. Add a reverse proxy so the site is reachable from the public internet.

3. Set up an Nginx reverse proxy

Install Nginx from N.WTF, then install the package:

sudo apt install nginx-extras -y

Create a configuration file at /etc/nginx/sites-available/example.com:

sudo bash -c 'cat > /etc/nginx/sites-available/example.com << "EOF"
upstream ghost {
  server 127.0.0.1:2368;
}

server {
  listen 443 ssl;
  listen [::]:443 ssl;
  listen 443 quic;
  listen [::]:443 quic;

  server_name example.com;

  access_log /var/log/nginx/example.com.access.log;
  error_log /var/log/nginx/example.com.error.log;

  add_header Alt-Svc '"'"'h3=":443"; ma=86400'"'"';
  add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"; 
  add_header X-Frame-Options SAMEORIGIN;
  add_header X-Content-Type-Options nosniff;
  add_header Referrer-Policy "strict-origin-when-cross-origin";

  location / {
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;
    proxy_set_header X-NginX-Proxy true;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "";
    proxy_redirect off;
    proxy_set_header        X-Forwarded-Proto $scheme;
    proxy_connect_timeout       300;
    proxy_send_timeout          300;
    proxy_read_timeout          300;
    send_timeout                300;
    proxy_pass http://ghost;
    proxy_hide_header X-powered-by;
  }

  ssl_protocols TLSv1.3;
  ssl_ecdh_curve X25519:prime256v1:secp384r1;
  ssl_prefer_server_ciphers off;

  ssl_certificate /etc/nginx/ssl/example.com.crt;
  ssl_certificate_key /etc/nginx/ssl/example.com.key;
}
EOF'

sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com

Replace example.com and the SSL certificate paths with your own domain and certificate files.

This config assumes the certificates already exist under /etc/nginx/ssl. To issue them, see How to Use nginx-acme on Debian/Ubuntu to Auto-Issue Let's Encrypt SSL for NGINX or How to Get Let's Encrypt SSL Certificates for IP Addresses with acme.sh.

Test the Nginx configuration and reload the service:

sudo nginx -t
sudo nginx -s reload

Visit https://example.com/ghost/ in your browser to open the Ghost admin screen.

4. Set up Caddy as a reverse proxy

If you do not want to manage certificates by hand, use Caddy instead of Nginx. It is less ceremony, which is nice when you would rather blog than negotiate TLS.

Caddy is an extensible, cross-platform, open-source web server written in Go. It requests and renews TLS certificates automatically.

Add the following lines to your Docker Compose YAML file:

  caddy:
    image: caddy:alpine
    container_name: caddy
    restart: always
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./caddy/etc/caddy:/etc/caddy
      - ./caddy/data:/data
      - ./caddy/config:/config
      - ./caddy/srv:/srv
    networks:
      - ghost-network

Or replace the Compose file with this full version:

cd /opt

echo 'name: ghost

services:
  ghost:
    image: ghost:6-alpine
    container_name: ghost
    restart: always
    ports:
      - 127.0.0.1:2368:2368
    environment:
      TZ: "UTC"
      database__client: mysql
      database__connection__host: ghost_database
      database__connection__user: ghost_user
      database__connection__password: YourRandomMySQLPassword
      database__connection__database: ghost_database
      mail__transport: smtp
      mail__from: "Your Name <noreply@example.com>"
      mail__options__service: Mailgun
      mail__options__host: smtp.mailgun.org
      mail__options__port: 465
      mail__options__auth__user: YourMailgunEmailUsername
      mail__options__auth__pass: YourMailgunEmailPassword
      mail__options__secure: true
      url: https://example.com/
    volumes:
      - ./data/ghost:/var/lib/ghost/content
    networks:
      - ghost-network

  ghost_database:
    image: mysql:8
    container_name: ghost_database
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: YourRandomMySQLRootPassword
      MYSQL_DATABASE: ghost_database
      MYSQL_USER: ghost_user
      MYSQL_PASSWORD: YourRandomMySQLPassword
    volumes:
      - ./data/mysql:/var/lib/mysql
    networks:
      - ghost-network

  caddy:
    image: caddy:alpine
    container_name: caddy
    restart: always
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./caddy/etc/caddy:/etc/caddy
      - ./caddy/data:/data
      - ./caddy/config:/config
      - ./caddy/srv:/srv
    networks:
      - ghost-network

  watchtower:
    image: nickfedor/watchtower:latest
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_POLL_INTERVAL=86400
    networks:
      - ghost-network

networks:
  ghost-network:
    name: ghost-network
' | sudo tee ./compose.yaml

Create a Caddyfile:

sudo mkdir -p ./caddy/etc/caddy

sudo bash -c 'cat > ./caddy/etc/caddy/Caddyfile << "EOF"
example.com {
    header {
        -Server
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Content-Type-Options "nosniff"
        X-Frame-Options "SAMEORIGIN"
        Referrer-Policy "strict-origin-when-cross-origin"
    }

    reverse_proxy http://ghost:2368 {
        header_up Host {host}
    }

    encode zstd gzip
}
EOF'

Pull all the images and start the containers:

docker compose pull
docker compose up -d

Wait a few minutes, then visit https://example.com/ in your browser.

Replace example.com with your own domain name in the Caddyfile. Also make sure your DNS A/AAAA records point to this server.

For a long time, Let's Encrypt issued certificates only for domain names. After several months of testing, Let's Encrypt made six-day and IP address certificates generally available on January 15, 2026.

1. Why issue certificates for IP addresses

Sometimes a domain name is unnecessary, but HTTPS is still required:

1. DNS over HTTPS (DoH) services that operate independently of domain resolution

   Running DoH directly on an IP address avoids the old philosophical headache: doing an insecure DNS lookup before opening a secure DNS connection.

2. Default server blocks that should not expose real names

   A default HTTPS vhost can present an IP certificate instead of leaking one of your real hostnames.

3. Temporary services or test environments

   You can bring up HTTPS without creating DNS records first.

4. Avoiding domain exposure in Certificate Transparency logs

   If a service does not need a domain name, an IP certificate avoids publishing that domain name in public CT logs.

2. Prerequisites

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands.

Update acme.sh first:

acme.sh --upgrade

IP address certificates can only use http-01 or tls-alpn-01 validation. Make sure your firewall allows public access to TCP port 80 and TCP/UDP port 443.

3. Configure the NGINX default server for port 80

Set up a default NGINX server block on port 80.

On Debian or Ubuntu systems with NGINX installed, replace /etc/nginx/sites-available/default with this configuration:

server {
    # Listen on port 80 for all IPv4 and IPv6 addresses
    listen 80 default_server;
    listen [::]:80 default_server;

    # Match all domain names
    server_name _;

    # Merge Let's Encrypt and SSL verification path configuration
    location ~ ^/.well-known/(acme-challenge|pki-validation)/ {
        add_header Content-Type text/plain;
        root /var/www/letsencrypt;
    }

    # Redirect all other HTTP requests to HTTPS using 301 permanent redirect
    location / {
        return 301 https://$host$request_uri;
    }
}

Create the required directories and reload NGINX:

sudo mkdir -p /var/www/letsencrypt
sudo mkdir -p /etc/nginx/ssl
sudo nginx -t
sudo nginx -s reload

4. Issue the IP address certificate with acme.sh

Assume your server's IP addresses are 192.0.2.2 and 2001:db8::2, and request the shortlived profile:

acme.sh --issue --server letsencrypt -d 192.0.2.2 -d 2001:db8::2 \
  -w /var/www/letsencrypt \
  --certificate-profile shortlived \
  --days 3

The shortlived profile is required for IP address certificates. Let's Encrypt limits these certificates to 160 hours, so acme.sh needs to check renewal more often than it would for a normal 90-day certificate. --days 3 checks every 3 days. A value of 4 or 5 can still work, but 6 or higher is asking for an avoidable expiry page.

If issuance succeeds, you will see output like this:

[Wed Dec 17 05:46:28 AM UTC 2025] Using CA: https://acme-v02.api.letsencrypt.org/directory
[Wed Dec 17 05:46:28 AM UTC 2025] Multi domain='IP:192.0.2.2,IP:2001:db8::2'
[Wed Dec 17 05:46:30 AM UTC 2025] Getting webroot for domain='192.0.2.2'
[Wed Dec 17 05:46:30 AM UTC 2025] Getting webroot for domain='2001:db8::2'
[Wed Dec 17 05:46:30 AM UTC 2025] Verifying: 192.0.2.2
[Wed Dec 17 05:46:31 AM UTC 2025] Pending. The CA is processing your order, please wait. (1/30)
[Wed Dec 17 05:46:34 AM UTC 2025] Success
[Wed Dec 17 05:46:34 AM UTC 2025] Verifying: 2001:db8::2
[Wed Dec 17 05:46:35 AM UTC 2025] Pending. The CA is processing your order, please wait. (1/30)
[Wed Dec 17 05:46:38 AM UTC 2025] Success
[Wed Dec 17 05:46:38 AM UTC 2025] Verification finished, beginning signing.
[Wed Dec 17 05:46:38 AM UTC 2025] Let's finalize the order.
[Wed Dec 17 05:46:38 AM UTC 2025] Le_OrderFinalize='https://acme-v02.api.letsencrypt.org/acme/finalize/blablablablablablablabla/blablablablablablablabla'
[Wed Dec 17 05:46:41 AM UTC 2025] Downloading cert.
[Wed Dec 17 05:46:41 AM UTC 2025] Le_LinkCert='https://acme-v02.api.letsencrypt.org/acme/cert/blablablablablablablabla'
[Wed Dec 17 05:46:42 AM UTC 2025] Cert success.
-----BEGIN CERTIFICATE-----
blablablablablablablablablablablablablablablablablablabla
-----END CERTIFICATE-----
[Wed Dec 17 05:46:42 AM UTC 2025] Your cert is in: /root/.acme.sh/192.0.2.2_ecc/192.0.2.2.cer
[Wed Dec 17 05:46:42 AM UTC 2025] Your cert key is in: /root/.acme.sh/192.0.2.2_ecc/192.0.2.2.key
[Wed Dec 17 05:46:42 AM UTC 2025] The intermediate CA cert is in: /root/.acme.sh/192.0.2.2_ecc/ca.cer
[Wed Dec 17 05:46:42 AM UTC 2025] And the full-chain cert is in: /root/.acme.sh/192.0.2.2_ecc/fullchain.cer

Install the issued certificate into /etc/nginx/ssl:

acme.sh --install-cert -d 192.0.2.2 \
  --key-file       /etc/nginx/ssl/ip.key  \
  --fullchain-file /etc/nginx/ssl/ip.crt \
  --ca-file        /etc/nginx/ssl/ip.ca.crt \
  --reloadcmd     "systemctl restart nginx"

5. Configure the NGINX default server for port 443

After installing the certificate, add the default HTTPS server block to /etc/nginx/sites-available/default:

# HTTPS server block for all HTTPS requests
server {
    # Standard TLS listening
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;

    # HTTP/2 protocol support
    http2 on;

    # HTTP/3 QUIC protocol support
    listen 443 quic reuseport;
    listen [::]:443 quic reuseport;
    add_header Alt-Svc 'h3=":443"; ma=86400' always;
    add_header X-Protocol $server_protocol always;

    # Match all domain names
    server_name _;
    return 403;

    # modern configuration
    ssl_protocols TLSv1.3;
    ssl_ecdh_curve X25519:prime256v1:secp384r1;
    ssl_prefer_server_ciphers off;

    ssl_certificate /etc/nginx/ssl/ip.crt;
    ssl_certificate_key /etc/nginx/ssl/ip.key;
}

Test the configuration and reload NGINX:

sudo nginx -t
sudo nginx -s reload

After this is configured, https://192.0.2.2/ returns a 403 page. Check the certificate details and the Subject Alt Names field should show IP Address:

1. What is nginx-acme?

nginx-acme is an official NGINX module that implements ACME. It lets NGINX request and renew TLS certificates without a separate ACME client.

If you have used Caddy, the idea will feel familiar: certificate automation lives in the web server config.

The module is implemented in Rust (unlike NGINX itself, which is written in C) and supports the following standards:

• RFC 8555 (ACME)
• RFC 8737 (TLS-ALPN-01)
• RFC 8738 (IP identifiers)
• draft-ietf-acme-profiles

In my testing, it has behaved well enough for production use. Still watch your logs, because certificate automation is one of those things you only notice when it stops working.

2. Install N.WTF (NGINX with nginx-acme)

This guide uses N.WTF, packaged by m.ac. Its nginx-extras package includes nginx-acme.

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands.

Install the required packages:

sudo apt update
sudo apt upgrade -y
sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates

Import the N.WTF signing key and add the APT repository:

curl -sSL https://n.wtf/public.key | sudo gpg --dearmor -o /usr/share/keyrings/n.wtf.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror-cdn.xtom.com/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

On Debian, extrepo can add the same repository:

sudo apt update
sudo apt install extrepo -y
sudo extrepo enable n.wtf

Install NGINX:

sudo apt update
sudo apt install nginx-extras -y

3. Prepare the certificate directory

Create a directory for ACME state and certificates. This example uses /var/cache/nginx/letsencrypt:

sudo mkdir -p /var/cache/nginx/letsencrypt
sudo chown 33:33 /var/cache/nginx -R

Make sure your domain's A and AAAA records point to this server before you continue.

4. Configure an NGINX site with a www redirect

This example assumes:

• Your domains are example.com and www.example.com
• You want www.example.com to redirect to example.com
• Your contact email is user@example.com

Edit /etc/nginx/sites-enabled/default and use this configuration:

resolver 8.8.8.8:53 ipv6=off valid=5s; # Or replace to your preferred DNS resolver

acme_issuer letsencrypt {
    uri         https://acme-v02.api.letsencrypt.org/directory;
    contact     user@example.com;
    state_path  /var/cache/nginx/letsencrypt;
    accept_terms_of_service;
    ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    ssl_verify on;
}

acme_shared_zone zone=ngx_acme_shared:1M;

server {
    # Listen on port 80 for ACME HTTP-01 validation and HTTP->HTTPS redirects
    listen 80 default_server;
    listen [::]:80 default_server;

    server_name _;

    # Let nginx-acme handle ACME HTTP-01 challenges.
    # Do not block /.well-known/acme-challenge/ here.
    location /.well-known/acme-challenge/ {
        # nginx-acme serves this internally.
        # Keeping the block empty avoids accidental 404s.
    }

    # Redirect all other HTTP requests to HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    # Standard TLS listening
    listen 443 ssl default_server;
    listen [::]:443 ssl default_server;

    # HTTP/2
    http2 on;

    # HTTP/3 (QUIC)
    listen 443 quic reuseport;
    listen [::]:443 quic reuseport;
    add_header Alt-Svc 'h3=":443"; ma=86400' always;
    add_header X-Protocol $server_protocol always;

    server_name example.com;

    root /var/www/html;
    index index.html;

    # Modern TLS settings
    ssl_protocols TLSv1.3;
    ssl_ecdh_curve X25519:prime256v1:secp384r1;
    ssl_prefer_server_ciphers off;

    # Enable certificate automation for this server block
    acme_certificate letsencrypt;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # Avoid parsing the certificate on every request
    ssl_certificate_cache max=2;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    http2 on;

    listen 443 quic;
    listen [::]:443 quic;

    add_header Alt-Svc 'h3=":443"; ma=86400' always;
    add_header X-Protocol $server_protocol always;

    server_name www.example.com;
    return 301 https://example.com$request_uri;

    ssl_protocols TLSv1.3;
    ssl_ecdh_curve X25519:prime256v1:secp384r1;
    ssl_prefer_server_ciphers off;

    acme_certificate letsencrypt;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    ssl_certificate_cache max=2;
}

Test the configuration and reload NGINX:

sudo nginx -t
sudo nginx -s reload

5. Verify certificate issuance

After NGINX reloads, nginx-acme requests a certificate. Watch the access log while it validates:

sudo tail -f /var/log/nginx/access.log

You should see requests to /.well-known/acme-challenge/ from Let's Encrypt validation servers. A few seconds later, https://example.com/ should answer with a valid certificate.

Example log entries:

23.178.112.210 - - [15/Jan/2026:16:08:18 +0000] "GET /.well-known/acme-challenge/blablablablablablablablablablablablablablab HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"
34.212.137.78 - - [15/Jan/2026:16:08:18 +0000] "GET /.well-known/acme-challenge/blablablablablablablablablablablablablablab HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

6. IP address certificates with the shortlived profile

To request a certificate for an IP address, add this line inside the acme_issuer letsencrypt {} block:

profile     shortlived;

Also set server_name to the full IP address. You cannot use server_name _ for an IP certificate.

RDAP stands for Registration Data Access Protocol.

The IETF developed RDAP as a structured replacement for the traditional WHOIS system.

RDAP provides standardized access to registration data for:

• Domains
• IP addresses (IPv4 / IPv6)
• ASNs (Autonomous System Numbers)

RDAP's original RFC set includes RFC 7480 through RFC 7484. Later documents obsolete and replace parts of the original set: RFC 9082, RFC 9083, and RFC 9224 supersede RFCs 7482, 7483, and 7484 respectively.

2. RDAP vs. WHOIS: what is different?

The short version:

In the old WHOIS world, clients connected to port 43, sent a plain-text query, and received whatever the server felt like sending back. For gTLDs, that world is already over: ICANN sunset port-43 WHOIS on January 28, 2025, making RDAP the definitive source for gTLD registration data. Many ccTLDs still run WHOIS, though.

Every registry had its own format. Sometimes the field for the registrant's email was Registrant Email, sometimes Contact Email, and sometimes something much stranger.

Developers had to write endless regex parsers just to extract data that should have been structured in the first place.

(If you have ever tried to parse WHOIS data, you probably still wake up sweating from that nightmare.)

The old WHOIS protocol has a few practical problems:

2.1 No structure, no standard API

Every registry returns data differently, so automation is painful.

2.2 No encryption

Port 43 uses plain text, so your ISP can see which domains you are querying. Not great.

2.3 No access control

WHOIS servers usually see only your IP address. They cannot reliably tell users apart, apply permissions, or enforce identity-based limits.

2.4 Messy management

Each TLD needs a custom WHOIS server definition because WHOIS has no global bootstrap list like RDAP.

3. Why RDAP is better for tools

RDAP fixes the worst parts of WHOIS and gives developers something they can parse without inventing a new regex crime scene.

3.1 Standardized JSON output

RDAP responses are structured JSON objects with clearly defined fields.

For example:

{
  "objectClassName": "domain",
  "ldhName": "example.com",
  "status": ["active"],
  "entities": [...]
}

No regex horror show. Your code gets JSON.

3.2 A unified API

RDAP runs over HTTP/HTTPS using a RESTful API.

You can make normal GET requests and script lookups in almost any language.

Example:

curl https://rdap.verisign.com/com/v1/domain/example.com

This returns structured data directly from the registry, without scraping.

3.3 Automatic bootstrap

RDAP clients do not need to know which registry to ask.

They follow IANA's bootstrap data to find the correct RDAP server for each TLD or RIR.

RDAP.org tracks deployment daily. Common gTLDs such as .com, .net, and .org already have RDAP base URLs in the bootstrap data, while many ccTLDs still do not.

For those TLDs, manual configuration or a fallback still matters.

3.4 Security and privacy

For gTLDs, RDAP runs over HTTPS, which avoids the plaintext leakage that comes with port 43 WHOIS.

Registries can also use OAuth 2.0 or token-based authentication and return different data based on the requester's role, such as public user, registrar, or law enforcement.

That makes it easier to expose public data while keeping restricted registration data behind the right access checks.

3.5 Extensibility

RDAP supports extensions, allowing registries to add custom fields without breaking compatibility.

Example:

"rdapConformance": ["rdap_level_0", "icann_rdap_technical_implementation_guide_0"]

Extensions let registries add fields without replacing the protocol.

4. Introducing RDAP.SS

I built a small WHOIS lookup site on top of RDAP: RDAP.SS

It uses Next.js, Tailwind CSS, and Redis caching, the usual suspects for a fast web app.

It supports queries in these formats:

• Domain → https://rdap.ss/whois/google.com
• IPv4 → https://rdap.ss/whois/8.8.8.8
• IPv4 CIDR → https://rdap.ss/whois/8.8.8.0/24
• IPv6 → https://rdap.ss/whois/2001:4860:4860::8888
• IPv6 CIDR → https://rdap.ss/whois/2001:4860::/32
• ASN → https://rdap.ss/whois/AS15169

Note: only TLDs with RDAP endpoints can be queried. If a registry does not have an RDAP endpoint yet, the lookup returns an error. Sorry, dot legacy fans.

If you run into a bug or have a feature idea, open an issue on GitHub.

What is extrepo?

The extrepo tool manages external repositories in Debian. Before extrepo, installing software that was not packaged for Debian usually meant writing APT configuration files by hand, running an unsigned script as root, or installing an unsigned .deb package that dropped repository configuration onto the system.

None of those options felt great.

Take the Docker repository as an example. Older instructions usually use one of these three methods.

The first is the traditional one-line style:

curl -sSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-ce.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-ce.gpg] https://download.docker.com/linux/debian $(lsb_release -sc) stable" | sudo tee /etc/apt/sources.list.d/docker-ce.list

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

The second uses the newer DEB822 format:

curl -sSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-ce.gpg

sudo bash -c 'cat > /etc/apt/sources.list.d/docker-ce.sources << EOF
Components: stable
Architectures: $(dpkg --print-architecture)
Suites: $(lsb_release -cs)
Types: deb
Uris: https://download.docker.com/linux/debian
Signed-By: /usr/share/keyrings/docker-ce.gpg
EOF'

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

Or you can use a Linux installation script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

With the first two methods, you download the GPG key, import it into the system, create the APT source files, and update the package lists yourself. The installation script does all of that for you, but the price is piping an unaudited remote script straight into a root shell and trusting whatever it decides to run.

With extrepo, that work becomes a couple of commands, and the repository metadata is GPG-verified against a keyring that ships in Debian itself.

Installing and using extrepo

The following steps require root privileges. The commands use sudo, so make sure your user can run it. You can also switch to root with sudo -i and remove the sudo prefix from the commands.

Install extrepo on Debian Stable:

sudo apt update
sudo apt install extrepo -y

After that, enable a third-party repository such as Docker CE:

sudo extrepo enable docker-ce

Once the repository is enabled, update your package lists and install Docker.

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

You will now have a new file named extrepo_docker-ce.sources in /etc/apt/sources.list.d:

$ cat /etc/apt/sources.list.d/extrepo_docker-ce.sources 
Suites: trixie
Types: deb
Uris: https://download.docker.com/linux/debian
Components: stable
Architectures: amd64 arm64 armhf s390x ppc64el
Signed-By: /var/lib/extrepo/keys/docker-ce.asc

In other words, extrepo takes care of the two annoying parts:

1. It fetches a verified GPG key.
2. It writes the APT configuration in DEB822 format.

You no longer have to search the web for repository snippets or installation scripts. The command is shorter, and more importantly, the repository metadata has a maintainer.

External repository metadata

The extrepo database is maintained by the Debian External Repositories Team, and the database itself is called extrepo-data.

I personally maintain several third-party software sources that we use on our servers, such as Redis, MariaDB, and N.WTF. You can view my commits here.

Anyone can contribute to this Git repository, and the YAML syntax is easy to learn. You can view the template here.

For a complete list of third-party repositories, browse the .yaml files here.

Where extrepo helps

extrepo is a cleaner way to add third-party repositories on Debian.

Its main advantage is boring, which is exactly what you want from repository configuration: it enables tested and verified software sources without making you copy keys and source files by hand. When a third-party repository's GPG key expires or its URI changes, which happens often enough to be annoying, you do not have to update it manually.

For Docker, run sudo extrepo enable docker-ce once. Later, sudo extrepo update docker-ce refreshes the repository's GPG key and URI.

The catch: extrepo currently supports Debian, while Ubuntu compatibility is limited. Also, because extrepo-data is hosted on Debian's official GitLab Pages, self-hosting it is still not especially convenient.

1. What is Mastodon?

Mastodon is a free, open-source, decentralized social network. It feels familiar if you have used Twitter or X, but one company does not own the whole thing.

Instead of everyone joining one central site, users create or join independently operated servers called instances that communicate across the wider Fediverse.

Running your own Mastodon instance gives you full control over your community, data, and content policies.

2. Prerequisites

Have these ready before you start:

• A domain name with DNS A/AAAA records pointed to your server's IP address. This tutorial uses example.com as the placeholder.

• A Linux server with Debian Stable or Ubuntu LTS installed and a user with sudo privileges.

• An email delivery service such as Mailgun or Amazon Simple Email Service.

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands.

Log in to your server and update the system:

sudo apt update
sudo apt upgrade -y
sudo apt full-upgrade -y

Install the required software and dependencies:

sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates -y

3. Add package repositories

Nginx

curl -sS https://n.wtf/public.key | sudo gpg --dearmor -o /usr/share/keyrings/n.wtf.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror-cdn.xtom.com/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

On Debian, you can also enable it with extrepo:

sudo apt install extrepo -y
sudo extrepo enable n.wtf

Node.js

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg

echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_24.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

Or use extrepo:

sudo apt install extrepo -y
sudo extrepo enable node_24.x

PostgreSQL

curl -sSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /usr/share/keyrings/postgresql.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/postgresql.gpg] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/postgresql.list

Or use extrepo:

sudo apt install extrepo -y
sudo extrepo enable postgresql

Redis

curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

Or use extrepo:

sudo apt install extrepo -y
sudo extrepo enable redis

Elasticsearch 8 (optional)

curl -sS https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/elasticsearch.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elasticsearch.list

Or use extrepo:

sudo apt install extrepo -y
sudo extrepo enable elastic_8

Update the package lists:

sudo apt update

4. Install system packages

Install the system packages Mastodon needs:

sudo apt install -y \
  imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git \
  g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
  bison build-essential libssl-dev libyaml-dev libreadline-dev \
  zlib1g-dev libncurses-dev libffi-dev libgdbm-dev \
  redis-server redis-tools postgresql postgresql-contrib \
  libidn11-dev libicu-dev libjemalloc-dev libvips nginx-extras

Enable Yarn through Corepack:

sudo corepack enable

Enable the redis-server service:

sudo systemctl enable --now redis-server

5. Create the Mastodon user

Create a dedicated mastodon user:

sudo adduser --disabled-password --gecos "" --home /home/mastodon mastodon

Then grant the right permissions for the /home/mastodon directory:

sudo chmod 0755 /home/mastodon

6. Set up PostgreSQL

Mastodon uses PostgreSQL as its database. Create a user named mastodon and allow it to create Mastodon's database:

sudo -u postgres psql
CREATE USER mastodon CREATEDB;
\q

You can use PGTune to tune PostgreSQL for your server.

PGTune generates recommended settings from your RAM and CPU. Treat them as a starting point, not sacred text.

7. Install Mastodon

Switch to the mastodon user and move into /home/mastodon. From here until you exit this shell, all commands run as the mastodon user without sudo:

sudo -i -u mastodon
cd ~

Install rbenv, a Ruby version manager:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Clone the Mastodon Git repository and switch to the latest released version:

cd ~
git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)

After checkout, install the Ruby version required by Mastodon:

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install

Install the Ruby and JavaScript dependencies:

bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --immutable

Wait for the install to finish before running the setup wizard.

8. Generate the Mastodon configuration file

Run the interactive setup wizard:

RAILS_ENV=production bin/rails mastodon:setup

This process will:

• Create a configuration file
• Run asset precompilation
• Create the database schema

The configuration file is saved as .env.production. You can review and edit it as needed. For detailed options, see the official documentation.

Leave the mastodon shell for now:

exit

9. Configure Nginx and SSL certificates

Use acme.sh to obtain free TLS certificates from Let's Encrypt. acme.sh is installed per user and its commands run without sudo; running this section as root (sudo -i) is recommended for reloading Nginx after certificate issuance:

cd ~
git clone https://github.com/acmesh-official/acme.sh.git
cd ./acme.sh
./acme.sh --install -m user@example.com
source ~/.bashrc
acme.sh --upgrade --auto-upgrade
acme.sh --set-default-ca --server letsencrypt

Replace user@example.com with your actual email address. If you leave the example address, Let's Encrypt will reject it with an error like this:

[Mon Apr 28 06:28:13 PM UTC 2025] Registering account: https://acme-v02.api.letsencrypt.org/directory
[Mon Apr 28 06:28:14 PM UTC 2025] Account registration error: {
  "type": "urn:ietf:params:acme:error:invalidContact",
  "detail": "Error creating new account :: contact email has forbidden domain \"example.com\"",
  "status": 400
}

Create a directory for Let's Encrypt HTTP-01 verification and another directory for the SSL certificates:

sudo mkdir -p /var/www/letsencrypt/.well-known/{acme-challenge,pki-validation}
sudo chown www-data:www-data /var/www/letsencrypt -R
sudo mkdir -p /etc/nginx/ssl

Modify the default Nginx configuration file.

sudo bash -c 'cat > /etc/nginx/sites-available/default << "EOF"
server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name _;

    location ~ ^/.well-known/(acme-challenge|pki-validation)/ {
      root /var/www/letsencrypt;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}
EOF'

This configuration redirects all requests on HTTP port 80 to HTTPS port 443, except for requests to /.well-known/acme-challenge/ and /.well-known/pki-validation/, which are served from the /var/www/letsencrypt directory.

The acme-challenge path is what Let's Encrypt uses for HTTP-01 validation. The pki-validation path is kept for other certificate workflows.

Reload Nginx:

sudo nginx -t
sudo nginx -s reload

Issue SSL certificates for your domain name:

acme.sh --issue -d example.com -w /var/www/letsencrypt

Replace example.com with your own domain name.

Install the certificates to /etc/nginx/ssl:

acme.sh --install-cert -d example.com \
--key-file       /etc/nginx/ssl/example.com.key  \
--fullchain-file /etc/nginx/ssl/example.com.crt \
--ca-file        /etc/nginx/ssl/example.com.ca.crt \
--reloadcmd     "sudo systemctl restart nginx"

You may need to add your current user to the sudoers file so acme.sh can restart Nginx without a password prompt. To do this, run:

sudo visudo

Add the following line at the end of the file:

your_username ALL=(ALL) NOPASSWD: /bin/systemctl restart nginx

Copy the Nginx configuration template from the Mastodon directory:

sudo cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
sudo ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon

The template needs three edits: your domain, your certificate paths, and one deleted block.

First, set your domain in a shell variable and let sed handle the renaming. The match side stays literal (that is exactly what the template says), and the replacement side carries your domain, so this works for any real domain:

DOMAIN=example.com
sudo sed -i \
  -e "s/server_name example.com;/server_name $DOMAIN;/g" \
  -e "s|# ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;|ssl_certificate     /etc/nginx/ssl/$DOMAIN.crt;|" \
  -e "s|# ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;|ssl_certificate_key /etc/nginx/ssl/$DOMAIN.key;|" \
  /etc/nginx/sites-available/mastodon

This sets server_name in both server blocks, and uncomments the two ssl_certificate lines while pointing them at the certificates acme.sh installed to /etc/nginx/ssl earlier.

Then open the file and delete the server block that starts with listen 80. Our default site from section 9 already redirects HTTP to HTTPS and serves the ACME challenges, so this block would only get in the way of renewals:

server {
  listen 80;
  listen [::]:80;
  server_name example.com;
  root /home/mastodon/live/public;
  location /.well-known/acme-challenge/ { allow all; }
  location / { return 301 https://$host$request_uri; }
}

After the edits, the top of the remaining server block should look like this:

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name example.com;

  ssl_protocols TLSv1.2 TLSv1.3;

  ssl_prefer_server_ciphers on;
  ssl_session_cache shared:SSL:10m;
  ssl_session_tickets off;

  ssl_certificate     /etc/nginx/ssl/example.com.crt;
  ssl_certificate_key /etc/nginx/ssl/example.com.key;

Create a cache folder for Nginx and reload it:

sudo mkdir -p /var/cache/nginx
sudo chown www-data:www-data /var/cache/nginx -R
sudo nginx -t
sudo nginx -s reload

10. Set up systemd services

Copy the systemd service templates from the Mastodon directory.

sudo cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/

Start and enable the new systemd services:

sudo systemctl daemon-reload
sudo systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

Visit https://example.com/ in your browser to open your Mastodon instance.

11. Enable Elasticsearch (optional)

Mastodon supports full-text search when Elasticsearch is available. Enable it only if your server has enough RAM and CPU; otherwise, keep the instance lighter and skip this section.

If you have already added the official Elasticsearch 8.x repository, install it with apt:

sudo apt install elasticsearch

Create a jvm.options file to configure Elasticsearch memory usage:

sudo bash -c 'echo "-Xms2g
-Xmx2g" > /etc/elasticsearch/jvm.options.d/jvm.options'

Elasticsearch 8 ships with security enabled but serves HTTPS with a self-signed certificate by default. For a localhost-only node it is simpler to keep authentication and turn off TLS on the HTTP layer:

echo "xpack.security.http.ssl.enabled: false" | sudo tee -a /etc/elasticsearch/elasticsearch.yml

Enable and start the systemd service:

sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch

Set a password for the built-in elastic user and note it down:

sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic

Edit the /home/mastodon/live/.env.production file and add the following lines, replacing password with the one you just generated:

# Elasticsearch (optional)
# ------------------------
ES_ENABLED=true
ES_HOST=localhost
ES_PORT=9200
# Authentication for ES (optional)
ES_USER=elastic
ES_PASS=password

Restart the Mastodon services so they read the new settings:

sudo systemctl restart mastodon-{web,sidekiq}

Run the following command to create the Elasticsearch indices and populate them with searchable data:

sudo -i -u mastodon
RAILS_ENV=production /home/mastodon/live/bin/tootctl search deploy

What is Debian?

Debian is a free and open source Linux distribution developed by the Debian Project, which Ian Murdock founded in August 1993. It is one of the oldest Linux distributions still in active use, and plenty of other distributions are built from it.

Debian 13, codenamed "Trixie", was released on August 9, 2025. This guide walks through upgrading Debian 12 "Bookworm" to Debian 13 "Trixie".

1. Prerequisites

Important: Make sure you are running on a dedicated server or a KVM/Xen-based VPS. OpenVZ and LXC are not supported for this upgrade.

Before you start, make a full backup of your system.

The following steps require root privileges. The commands use sudo, so make sure your user can run it. You can also switch to root with sudo -i and remove the sudo prefix from the commands.

2. Update system

Start by bringing the current Debian 12 system fully up to date:

sudo apt update
sudo apt upgrade -y
sudo apt full-upgrade -y
sudo apt autoclean
sudo apt autoremove -y

If the kernel was updated, reboot before moving on. It is optional, but I recommend doing it anyway.

3. Upgrade to Debian 13

Replace bookworm with trixie in your APT source files:

sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/*.list
sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list.d/*.sources

If the .list or .sources files are missing, you may see this error. You can ignore it:

sed: can't read /etc/apt/sources.list.d/*.sources: No such file or directory

Or run the same replacement as one command:

sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list /etc/apt/sources.list.d/*.{list,sources} 2>/dev/null

Your default /etc/apt/sources.list should then look like this:

deb https://deb.debian.org/debian trixie main contrib non-free non-free-firmware

deb https://security.debian.org/debian-security trixie-security main contrib non-free non-free-firmware

deb https://deb.debian.org/debian trixie-updates main contrib non-free non-free-firmware

If you use the DEB822 source format, /etc/apt/sources.list.d/debian.sources should look like this:

Types: deb
URIs: https://deb.debian.org/debian
Suites: trixie trixie-updates trixie-backports
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Types: deb
URIs: https://security.debian.org/debian-security
Suites: trixie-security
Components: main contrib non-free non-free-firmware
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg

Now update the package lists and run the upgrade:

sudo apt update
sudo apt upgrade -y
sudo apt full-upgrade -y

If you remove the -y option, apt will ask before installing updates, restarting services, and making a few other changes. In the normal upgrade path, you can answer Yes.

For some configuration files, choose the option that fits your server. Pressing Enter usually keeps the existing file. You will often see this with packages such as OpenSSH.

When the apt-listchanges: News interface appears, you can press q to exit.

For service restarts during package upgrades, you can choose the option to restart without asking:

When prompted about a modified configuration file, choose whether to keep yours or install the package maintainer's version:

Some package updates change systemd service definitions. If you see a warning about that, run sudo systemctl daemon-reload to reload the updated configuration.

Once the upgrade is complete, remove packages and dependencies that are no longer needed:

sudo apt autoclean
sudo apt autoremove -y

Reboot with sudo reboot, then verify the installed Debian version:

root@debian ~ # cat /etc/debian_version 
13.0

root@debian ~ # lsb_release -a
No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 13 (trixie)
Release:	13
Codename:	trixie

root@debian ~ # uname -a
Linux n 6.12.41+deb13-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.12.41-1 (2025-08-12) x86_64 GNU/Linux

That is it. The system is now running Debian 13 with the new kernel.

ICANN's January 27, 2025 update made RDAP the definitive source for gTLD registration data, with legacy WHOIS services retired. For new registration data lookups, use RDAP.

The Registration Data Access Protocol (RDAP) is the successor to the traditional WHOIS protocol. It uses HTTPS and structured responses instead of unencrypted, loosely formatted text over port 43.

If you run registry or registrar infrastructure, move clients to RDAP rather than keeping a full WHOIS service around forever. We have already completed that migration for xTom GmbH (IANA ID 3968).

Old applications still query WHOIS on port 43, so this server keeps compatibility clients from failing silently. It accepts the connection and returns a plain message that points users to RDAP.

1. Prerequisites

There are two straightforward ways to build this kind of WHOIS compatibility endpoint: Nginx stream alone, or a small Python service behind Nginx.

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands.

Install the required packages:

sudo apt update
sudo apt install -y lsb-release ca-certificates apt-transport-https curl gnupg dpkg python3

Add the N.WTF repository, which provides an Nginx mainline build with the stream module enabled:

curl -sS https://n.wtf/public.key | sudo gpg --dearmor -o /usr/share/keyrings/n.wtf.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror-cdn.xtom.com/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

Install Nginx:

sudo apt install nginx-extras -y

2. Build a WHOIS server with the Nginx stream module

The Nginx stream module can return a fixed message on port 43. Add this block to /etc/nginx/nginx.conf:

stream {
    # Define rate limiting zone
    limit_conn_zone $binary_remote_addr zone=whois_stream_conn:10m;

    # simple whois server
    server {
        listen 43;
        listen [::]:43;

        # Connection limits
        limit_conn whois_stream_conn 5;

        proxy_timeout 10s;

        # Return a message to the client
        return "NOTICE: In accordance with ICANN compliance policies, our whois server has been discontinued. Please use the RDAP protocol for all domain whois queries.\n\nFor more information, please visit:\n\nhttps://www.icann.org/en/announcements/details/icann-update-launching-rdap-sunsetting-whois-27-01-2025-en\nhttps://www.icann.org/resources/pages/global-amendment-2023-en\n\n";
    }
}

Test the configuration and reload Nginx:

sudo nginx -t
sudo nginx -s reload

Some WHOIS clients do not like this version. A query may print:

fgets: Connection reset by peer

The Nginx stream return approach writes the message and closes the TCP session immediately. That is enough for some clients, but others report fgets: Connection reset by peer instead of printing the text cleanly.

Using a tiny Python service gives us better control over reading the query, writing the response, and closing the connection.

3. Build a WHOIS server with Python and Nginx

The Python script listens locally and returns a predefined message to each WHOIS client.

Clone the repository and copy whois.py to /opt/:

git clone https://git.m.ac/showfom/whois-server
cd whois-server
sudo cp -r whois.py /opt

Copy the systemd service template to /etc/systemd/system/:

sudo cp -r whois-server.service /etc/systemd/system/

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now whois-server

Test the WHOIS service locally:

whois anything -h 127.0.0.1:10043

It should return the configured message:

NOTICE: In accordance with ICANN compliance policies, our whois server has been discontinued. Please use the RDAP protocol for all domain whois queries.

For more information, please visit:

https://www.icann.org/en/announcements/details/icann-update-launching-rdap-sunsetting-whois-27-01-2025-en
https://www.icann.org/resources/pages/global-amendment-2023-en

Now configure Nginx to proxy public port 43 traffic to the local Python service.

Add this block to /etc/nginx/nginx.conf:

stream {
    # Define rate limiting zone
    limit_conn_zone $binary_remote_addr zone=whois_stream_conn:10m;

    # whois server
    server {
        listen 43;
        listen [::]:43;

        # Connection limits
        limit_conn whois_stream_conn 5;

        # Forward requests to the local Python script service
        proxy_pass 127.0.0.1:10043;
        proxy_timeout 30s;
    }
}

Test the configuration and reload Nginx:

sudo nginx -t
sudo nginx -s reload

Query the public WHOIS endpoint:

whois anything -h localhost

You can also create a WHOIS hostname with A and AAAA records pointing to this server, then submit that hostname wherever a registry still asks for an official WHOIS server.

What is Docker?

Docker packages an application and its dependencies into containers so it runs the same way on your laptop, a test box, and a production server. Fewer "it works on my machine" mysteries, which is usually worth the trouble.

What is Docker Compose?

Docker Compose manages multi-container Docker applications from one YAML file. You define the services once, then start them with a single command instead of juggling a small circus of docker run flags.

1. Prerequisites

Make sure you have installed Debian Stable (either oldstable or stable releases, sid is not supported) or Ubuntu LTS (Interim releases not supported).

The commands below use sudo. If you prefer a root shell, run sudo -i first and drop sudo from the commands. The docker commands are not prefixed with sudo: add your user to the docker group (sudo usermod -aG docker $USER, then log out and back in), or add sudo yourself.

Update your system and install the required tools.

sudo apt update -y
sudo apt upgrade -y
sudo apt full-upgrade -y
sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates -y

2. Install Docker and Docker Compose

2.1 Add Docker's GPG key

curl -sSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-ce.gpg

2.2 Add the Docker repository

Debian:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-ce.gpg] https://download.docker.com/linux/debian $(lsb_release -sc) stable" | sudo tee /etc/apt/sources.list.d/docker.list

On Debian, you can also enable it with extrepo:

sudo apt install extrepo -y
sudo extrepo enable docker-ce

Ubuntu:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-ce.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -sc) stable" | sudo tee /etc/apt/sources.list.d/docker.list

2.3 Install

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Check the installed Docker version:

$ docker version
Client: Docker Engine - Community
 Version:           29.6.1
 API version:       1.55
 Go version:        go1.26.4
 Git commit:        8900f1d
 Built:             Fri Jun 26 11:40:34 2026
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          29.6.1
  API version:      1.55 (minimum version 1.40)
  Go version:       go1.26.4
  Git commit:       8ec5ab3
  Built:            Fri Jun 26 11:40:34 2026
  OS/Arch:          linux/amd64
  Experimental:     true
 containerd:
  Version:          v2.2.5
  GitCommit:        e53c7c1516c3b2bff98eb76f1f4117477e6f4e66
 runc:
  Version:          1.3.6
  GitCommit:        v1.3.6-0-g491b69ba
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad

Check Docker Compose too:

$ docker compose version
Docker Compose version v5.3.

3. Add IPv6 support

By default, Docker does not enable IPv6 for bridge networks. To turn it on, add the IPv6 settings to the Docker daemon configuration.

Warning: Some containers do not behave well with IPv6. Test the applications you plan to run before relying on it in production.

Create or edit the Docker daemon configuration file:

sudo bash -c 'cat > /etc/docker/daemon.json << EOF
{
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "20m",
        "max-file": "3"
    },
    "userland-proxy": false,
    "ipv6": true,
    "fixed-cidr-v6": "fdba::/64",
    "experimental":true,
    "ip6tables":true
}
EOF'

Restart Docker so it reads the new configuration:

sudo systemctl restart docker

Test IPv6 support by creating a Docker network named ipv6_network:

docker network create --ipv6 --subnet=fd00::/64 ipv6_network

Then use the curlimages/curl image to make an IPv6 request:

docker run --rm --network ipv6_network curlimages/curl:latest curl -6 ip.sb -s

If the command prints your public IPv6 address, Docker's IPv6 bridge networking is working.

4. Use rootless mode (optional)

Rootless mode lets the Docker daemon and containers run as a non-root user. That reduces the damage if something goes wrong, although it does not make containers magically harmless.

Warning: Some containers do not work in rootless mode. If a container behaves strangely, test it with regular Docker before blaming the application.

Install the required system packages:

sudo apt install uidmap dbus-user-session docker-ce-rootless-extras

Note: The docker-ce-rootless-extras package is already included in the Docker installation.

Create a new user named showfom, or use another name if you prefer:

sudo adduser --disabled-password --gecos "" --home /home/showfom showfom

Disable the currently running Docker services:

sudo systemctl disable --now docker.service docker.socket
sudo rm /var/run/docker.sock

Enable lingering for the showfom user, so its systemd user manager (and the rootless Docker daemon under it) starts at boot and survives logout:

sudo loginctl enable-linger showfom

Switch to the showfom user and run the dockerd-rootless-setuptool.sh script. Use machinectl shell rather than su: the setup script talks to systemctl --user, which needs a real systemd login session that sudo su - does not provide:

sudo machinectl shell showfom@
/usr/bin/dockerd-rootless-setuptool.sh install

If machinectl is missing, install it with sudo apt install systemd-container -y.

You should see output similar to the following:

$ dockerd-rootless-setuptool.sh install
[INFO] Creating /home/showfom/.config/systemd/user/docker.service
[INFO] starting systemd service docker.service
+ systemctl --user start docker.service
+ sleep 3
+ systemctl --user --no-pager --full status docker.service
● docker.service - Docker Application Container Engine (Rootless)
     Loaded: loaded (/home/showfom/.config/systemd/user/docker.service; disabled; preset: enabled)
     Active: active (running) since Wed 2025-04-30 14:53:19 UTC; 3s ago
       Docs: https://docs.docker.com/go/rootless/
   Main PID: 227068 (rootlesskit)
      Tasks: 39
     Memory: 58.2M
        CPU: 398ms
     CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/docker.service
             ├─227068 rootlesskit --state-dir=/run/user/1000/dockerd-rootless --net=slirp4netns --mtu=65520 --slirp4netns-sandbox=auto --slirp4netns-seccomp=auto --disable-host-loopback --port-driver=builtin --copy-up=/etc --copy-up=/run --propagation=rslave /usr/bin/dockerd-rootless.sh
             ├─227080 /proc/self/exe --state-dir=/run/user/1000/dockerd-rootless --net=slirp4netns --mtu=65520 --slirp4netns-sandbox=auto --slirp4netns-seccomp=auto --disable-host-loopback --port-driver=builtin --copy-up=/etc --copy-up=/run --propagation=rslave /usr/bin/dockerd-rootless.sh
             ├─227104 slirp4netns --mtu 65520 -r 3 --disable-host-loopback --enable-sandbox --enable-seccomp 227080 tap0
             ├─227112 dockerd
             └─227132 containerd --config /run/user/1000/docker/containerd/containerd.toml

Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393381898Z" level=warning msg="WARNING: No io.max (rbps) support"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393387228Z" level=warning msg="WARNING: No io.max (wbps) support"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393393279Z" level=warning msg="WARNING: No io.max (riops) support"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393398720Z" level=warning msg="WARNING: No io.max (wiops) support"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393415330Z" level=info msg="Docker daemon" commit=01f442b containerd-snapshotter=false storage-driver=overlay2 version=28.1.1
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393481325Z" level=info msg="Initializing buildkit"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.420441982Z" level=info msg="Completed buildkit initialization"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.425685368Z" level=info msg="Daemon has completed initialization"
Apr 30 14:53:19 m dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.425749069Z" level=info msg="API listen on /run/user/1000/docker.sock"
Apr 30 14:53:19 m systemd[226972]: Started docker.service - Docker Application Container Engine (Rootless).
+ DOCKER_HOST=unix:///run/user/1000/docker.sock /usr/bin/docker version
Client: Docker Engine - Community
 Version:           28.1.1
 API version:       1.49
 Go version:        go1.23.8
 Git commit:        4eba377
 Built:             Fri Apr 18 09:52:57 2025
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          28.1.1
  API version:      1.49 (minimum version 1.24)
  Go version:       go1.23.8
  Git commit:       01f442b
  Built:            Fri Apr 18 09:52:57 2025
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.27
  GitCommit:        05044ec0a9a75232cad458027ca83437aae3f4da
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0
 rootlesskit:
  Version:          2.3.4
  ApiVersion:       1.1.1
  NetworkDriver:    slirp4netns
  PortDriver:       builtin
  StateDir:         /run/user/1000/dockerd-rootless
 slirp4netns:
  Version:          1.2.0
  GitCommit:        656041d45cfca7a4176f6b7eed9e4fe6c11e8383
+ systemctl --user enable docker.service
Created symlink /home/showfom/.config/systemd/user/default.target.wants/docker.service → /home/showfom/.config/systemd/user/docker.service.
[INFO] Installed docker.service successfully.
[INFO] To control docker.service, run: `systemctl --user (start|stop|restart) docker.service`
[INFO] To run docker.service on system startup, run: `sudo loginctl enable-linger showfom`

[INFO] Creating CLI context "rootless"
Successfully created context "rootless"
[INFO] Using CLI context "rootless"
Current context is now "rootless"

[INFO] Make sure the following environment variable(s) are set (or add them to ~/.bashrc):
export PATH=/usr/bin:$PATH

[INFO] Some applications may require the following environment variable too:
export DOCKER_HOST=unix:///run/user/1000/docker.sock

Add the following environment variables:

echo 'export PATH=/usr/bin:$PATH' >> ~/.bashrc
echo 'export DOCKER_HOST=unix:///run/user/1000/docker.sock' >> ~/.bashrc
source ~/.bashrc

Enable the Docker service for the user:

systemctl --user enable --now docker
systemctl --user status docker

You will see output like this:

$ systemctl --user status docker
● docker.service - Docker Application Container Engine (Rootless)
     Loaded: loaded (/home/showfom/.config/systemd/user/docker.service; enabled; preset: enabled)
     Active: active (running) since Wed 2025-04-30 14:53:19 UTC; 1min 13s ago
       Docs: https://docs.docker.com/go/rootless/
   Main PID: 227068 (rootlesskit)
      Tasks: 39
     Memory: 58.3M
        CPU: 463ms
     CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/docker.service
             ├─227068 rootlesskit --state-dir=/run/user/1000/dockerd-rootless --net=slirp4netns --mtu=65520 --slirp4netns-sandbox=auto ->
             ├─227080 /proc/self/exe --state-dir=/run/user/1000/dockerd-rootless --net=slirp4netns --mtu=65520 --slirp4netns-sandbox=aut>
             ├─227104 slirp4netns --mtu 65520 -r 3 --disable-host-loopback --enable-sandbox --enable-seccomp 227080 tap0
             ├─227112 dockerd
             └─227132 containerd --config /run/user/1000/docker/containerd/containerd.toml

Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393381898Z" level=warning msg="WARNING: No io.max (rbps) suppor>
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393387228Z" level=warning msg="WARNING: No io.max (wbps) suppor>
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393393279Z" level=warning msg="WARNING: No io.max (riops) suppo>
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393398720Z" level=warning msg="WARNING: No io.max (wiops) suppo>
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393415330Z" level=info msg="Docker daemon" commit=01f442b conta>
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.393481325Z" level=info msg="Initializing buildkit"
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.420441982Z" level=info msg="Completed buildkit initialization"
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.425685368Z" level=info msg="Daemon has completed initialization"
Apr 30 14:53:19 debian dockerd-rootless.sh[227112]: time="2025-04-30T14:53:19.425749069Z" level=info msg="API listen on /run/user/1000/docker>
Apr 30 14:53:19 debian systemd[226972]: Started docker.service - Docker Application Container Engine (Rootless).

Docker is installed. Time to make sure Compose works too.

Note: Docker rootless mode has limits, and some containers are not compatible with it.

5. Try Docker Compose

A tiny Nginx site is enough to check that Docker Compose is behaving.

Create a new directory, generate an index.html file, and add a simple Nginx configuration file named default.conf:

mkdir html

echo 'Hello World' > ./html/index.html

echo 'server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name  _;
    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }
}' > ./default.conf

Create a file named compose.yaml:

echo 'name: nginx

services:
  nginx:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html
      - ./default.conf:/etc/nginx/conf.d/default.conf
    restart: always
    networks:
      - nginx-network
      
networks:
  nginx-network:
    name: nginx-network
    enable_ipv6: true
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 192.168.0.0/24
          gateway: 192.168.0.1
        - subnet: "fdba::/64"
          gateway: "fdba::1"' > ./compose.yaml

Pull the required container images:

docker compose pull

After the Nginx image has been pulled, start the container:

docker compose up -d

Use docker ps to check that the container is running:

$ docker ps
CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS         PORTS                                     NAMES
2e11699fbc47   nginx:latest   "/docker-entrypoint.…"   5 seconds ago   Up 5 seconds   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp   nginx-nginx-1

Test Nginx over both IPv4 and IPv6.

IPv4:

curl localhost:8080 -4

IPv6:

curl localhost:8080 -6

If both commands print Hello World, Compose is doing its job. Stop the stack with docker compose down.