Unstable Muffin - how-to

How To: Migrate a PostgreSQL database

2026-04-21T00:00:00-07:00

This article will show you how to migrate a database from one PostgreSQL server to another.

Before starting the database migration, stop the service that is accessing the database to prevent a corrupt backup and/or missing data. This should also flush any cached data to the disk.

On the old server

Dump the database contents from the old database to a file.

pg_dump [-h <ip_address>] -U <user> -d <database> -f <backup_file>.sql

pg_dump – This is a PostgreSQL utility command that dumps all the data from a PostgreSQL database to a file. This includes not only the data but also indexes, schema, autoincrement states, and everything else that represents the state of the database at the time the backup was made.
-h <ip_address> – This specifies where to find the PostgreSQL database to dump from. If this command is run on the same machine as the database, it can be omitted and will default to the current machine.
-U <user> – This is the username of the SQL user to access the database. Make sure it has permissions to access the database.
-d <database> – The name of the database to backup.
-f <backup_file>.sql – This specifies the name of the file to dump the database to. Note that the output of this command is plaintext SQL statements, so the file extension should be .sql.

The contents of the backup file is plaintext SQL, so you can view and modify the backup if desired. This can be helpful to adjust usernames, database names, and permissions if you want them to be different on the new server than the old one. When the backup is restored, it will execute every line in the file one-by-one to recreated the database. Any changes to the backup will be executed as well.

On the new server

First, connect to the new database.

sudo -u postgres psql

Create the database user.

CREATE USER <db_user> WITH PASSWORD '<password>';

Create the database.

CREATE DATABASE <db_name> OWNER <db_user>;

Finally, grant the new user all permissions and privileges on the newly created database.

GRANT ALL ON SCHEMA public TO <db_user>;

Once the user and database are created in the new server, you can exit the PostgreSQL command line (\q). The next step is to configure PostgreSQL to allow access to the new database for this user. Open the access configuration file for PostgreSQL in any editor.

sudo nano /etc/postgresql/<version>/main/pg_hba.conf

And add a line like the following:

# TYPE   DATABASE        USER            ADDRESS            METHOD
<type>   <database>      <db_user>       <ip_address>       <auth_type>

<type> – This specifies the type of connection. Valid options include local, host, hostssl, and hostnossl. local is for connections over the PostgreSQL Unix socket. host is for TCP/IP connections (either remote or via localhost). hostssl and hostnossl are for specifically TCP/IP conections that are required to have SSL encryption or not.
<database> – This is the name of the database this record allows access to.
<db_user> – This is the user that is being allowed access to the above database.
<ip_address> – This is the IP address from which the specified user is allowed to connect to the specified database. The format should be IP address and subnet. A subnet of /32 corresponds to a single IP address, so something like 127.0.0.1/32 would correspond to only allowing connections from localhost over IPv4. For access from Docker containers, which have dynamic IP addresses, you should whitelist the entire Docker subnet: 172.22.0.0/16.
<auth_type> – This is the type of authentication required for this method of access. Options include trust, reject, md5, password, scram-sha-256, and peer, among others.
trust will implicitly trust this connection and not require any authentication at all.
reject will reject this connection. This is useful in conjuction with other records, which allow you to fine tune access. Records are evaluated from top to bottom and terminate on the first match, so you can reject a specific IP address at the top of the file, and then accept a broader range of IP addresses lower in the file.
md5 will accept a password with SCRAM-SHA-256 or MD5 hashing algorithm. MD5 is easily cracked with modern machines and is not considered secure. This authentication method is deprecated and will be removed in future version of PostgreSQL.
password requires the client to send their password unencrypted to the server. The password is transmitted in cleartext, so this authentication method is not recommended on untrusted networks.
scram-sha-256 will required strong encryption for the password.
peer authentication will check if the user connecting has an OS account that matches the name of a database user. If so, it will allow the connection. This authentication method is only valid on local connection types.

If you intend to allow connections from other devices or networks, you must change PostgreSQL’s configuration to bind to all network interfaces. By default it is only bound to localhost, and connections from another network (e.g. another computer or even Docker running on the same machine) will fail.

To configure PostgreSQL to bind to all available interfaces, modify the config file at /etc/postgresql/<version>/main/postgresql.conf and change the following line:

listen_addresses = '*'

After saving the changes to the configuration, trigger a reload to force PostgreSQL to update its configuration. If you changed the listen_addresses config, you must restart the PostgreSQL service instead of just reloading it.

sudo systemctl reload postgresql

Finally, restore the database backup to the new database.

psql [-h <ip_address>] -U <user> -d <database> -f <backup_file>.sql

psql – This is the command that connects to a PostgreSQL server.
-h <ip_address> – Host of the new database server. If the backup file was copied to the new server and this command is being run on the same device as the database being restored to, this can be omitted.
-U <user> – The username to connect with. Should be the same as the old one.
-d <database> – The database name. Should be the same as the old one.
-f <backup_file>.sql – The file containing the backed up data created from pg_dump.

Now the data should be restored to the new database. Point the service to the new database and start it up, and it should connect and appear that nothing has changed.

How To: Install Steam mods on Linux

2026-03-18T00:00:00-07:00

When you install a mod for a Steam game on Linux, it may not work correctly in the game. In many cases this is due to the differences in the way Windows and Linux interpret file names. In Windows, file names are case-insensitive, meaning MyFile.txt and myfile.txt refer to the same file on the disk. In contrast, on Linux file names are case sensitive, so those two file names would refer to different files.

Since Windows dominates the gaming scene, most mods are developed on Windows computers, where the casing of file names doesn’t matter. This leads to modders getting lazy with their filenames and often using a different casing than the game uses. While the mod might work without issue on Windows, on Linux the mod will fail in unexpected ways when it tries to reference files that may or may not exist (at least, as Linux sees them).

The solution to this problem is to install a virtual file system on your Linux computer that will emulate a Windows file system with case insensitive filenames. When the mod loads files from this virtual file system, it loads files with any casing correctly while the game itself continues natively on Linux. The steps below will show you how to create the virtual file system and then mount it for use with your games. You don’t have to reinstall your mods this way either; they can be copied over to the new file system and should start working immediately.

Create the virtual file system

To start with, you need to create the virtual file system. We will be using the vFAT file system for this purpose. vFAT is a lightweight, Windows-compatible file system with native support in the Linux kernel. It’s significantly faster to use compared with a full NTFS file system, since NTFS provides a bunch of features that are not needed for a small virtual file system and it requires additional driver support in Linux.

To create the virtual file system, run this command:

sudo mkfs.vfat -C -F 32 /opt/steam-workshop.img 2097152

mkfs.vfat - This command creates a virtual file system using the FAT file system format.
-C - This option specifies that the command should create a file instead of using an existing physical device like a USB stick.
-F 32 - This option specifies using FAT32 format, allowing the largest file sizes in the FAT family.
/opt/steam-workshop.img - This specifies the file where you want to file system to be stored. This can be any place and any name you want. If you use a different path or name, be sure to change in the rest of the commands below.
2097152 - This is the size of the file system you want to create. This number is the number of file system blocks, which the mkfs.vfat command defaults to 1024 bytes each, or 1 KB. So this number should be how many kilobytes the file should be. E.g. 1 MB is 1024 KB, and 1 GB is 1048576 KB. I chose 2097152 blocks for mine, which equates to 2 GB. You can adjust this value depending on how many mods you want to be able to install at one time.

Run this command as root on your system and verify it created a new file at the specified path. It is already formatted with the FAT32 file system, so next we need to use it.

Mounting the virtual file system

You can’t access the virtual file system directly through the file we created in the last step; it must be mounted to the local file system as a virtual block device so it can be used by the operating system. To do that, we’ll use a loopback device.

Choosing a loopback device

Loopback devices typically use the naming convention /dev/loopXX where XX is any numeric digit. To see if you have any loopback devices in use already, you can run the command losetup -l. If you don’t see loopback devices listed, then you are free to pick any number, or start at 0. If you do see any loopback devices, just choose a number that’s not in use. You can either use the next available number, or choose an arbitrary higher number to leave room for other programs creating loopback devices.

To create the loopback device, run the following command:

losetup /dev/loopXX /opt/steam-workshop.img

losetup - This is the name of the program that creates, manages, and deletes loopback devices on your system.
/dev/loopXX - This is the loopback device to create. Replace the XX with number you chose previously.
/opt/steam-workshop.img - This is the path to the virtual file system you created in the previous section.

If the command ran successfully, the virtual file system file is now running as a block device on your system. The next step is to mount it so your operating system can access the files in it.

Manually mounting the virtual file system

Next, you can mount the virtual file system by running the following command:

sudo mount -o uid=<user>,gid=users,fmask=113,dmask=002,iocharset=iso8859-1 /dev/loopXX "/path/to/steam/steamapps/workshop/content"

sudo mount - This command mounts file systems into your root file system for the operating system to use. It must always be run as the root user.
-o uid=<user>,gid=users,fmask=113,dmask=002,iocharset=iso8859-1 - This specifies the options for the file system to be mounted. Replace <user> with your username. The uid and gid options specify the user and group that the file system should be mounted with. The fmask and dmask options set the file permissions. And finally iocharset sets the character encoding for filenames.
/dev/loopXX - This is the loopback device you created previously. Replace XX with the number of the loopback device you created.
"/path/to/steam/steamapps/workshop/content" - This is the path to the workshop content (mods + other downloadable content from Steam) on your computer. It can vary from system to system and the way Steam was installed. But once you find the directory steam is installed at, inside you should find the steamapps/workshop/content folder where any current mods for any game are installed. Note the double quotes around the path. If there’s already content inside this folder, be sure to back it up before mounting this directory! It’s as simple as cp -r content/ content_old/.

After running this command, the virtual file system should be mounted in Steam’s content directory, meaning any files the Steam workshop downloads to your computer will be stored in the virtual file system instead of on your disk.

If you backed up existing files from the content directory, you can use this command to restore those files:

cp -a content_old/* content/

The -a flag will recursively copy all files, preserving file permissions, ownership, timestamps, and extended attributes. Just make sure the content/ directory is empty, as this command will overwrite any files with the same name.

Automatically mounting the file system

If you followed the instructions previously to manually mount the virtual file system, you will notice that it will become unmounted every time you turn off the computer. You can create a systemd service to automatically mount the file system at boot.

First, create the service file using your favorite text editor. I’m using nano because it’s objectively the best. The file can be named whatever you want, as long as it ends with .service and can be found in the /etc/systemd/system/ directory. If you use a different service name, be sure to change the name in the rest of the commands.

sudo nano /etc/systemd/system/steam-workshop.service

And add the following content to it:

[Unit]
Description=Steam Workshop virtual drive device and mount
After=local-fs.target
Before=graphical.target

[Service]
Type=oneshot
ExecStart=/bin/bash -c '/sbin/losetup /dev/loopXX /opt/steam-workshop.img && /bin/mount -o uid=<usr>,gid=users,fmask=113,dmask=002,iocharset=iso8859-1 /dev/loopXX "/path/to/steam/steamapps/workshop/content"'
ExecStop=/bin/bash -c '/bin/umount "/path/to/steam/steamapps/workshop/content" && /sbin/losetup -d /dev/loopXX'
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Here are the important things to note about this service file:

Description= - The description for this systemd service. You can put anything here.
After=local-fs.target - This will prevent this service from starting until after the local file system has been initialized. This is important because we are loading from an existing file on the local file system, so we have to make sure the local file system is fully initialized before mounting the virtual file system.
Before=graphical.target - This specifies that the graphical subsystem should not start until this service completes. That means the virtual file system should be mounted before the graphics system is initialized. This is helpful if you have Steam set to start at system startup: it will prevent Steam from auto-starting before the virtual file system has been mounted, causing Steam to see an empty content/ directory.
Type=oneshot - This specifies that this command will run a single command and terminate (as opposed to a daemon that runs forever). This informs systemd how to manage and report the status of this service.
ExecStart= - This is what systemd will run when it starts your service. It should look similar to the steps to manually mount the virtual file system. Things to note about this command:
- It combines both the creation of the loopback device and mounting it into one command, joined by &&. The whole thing is wrapped in a call to /bin/bash -c '...' because systemd can only run one command. Note the single quotes; since the command uses double quotes around the file path, we use single quotes here to not interfere with those.
- We use the full path to /sbin/losetup instead of just the command name itself. Since this is running early on in the boot process, it’s safer to refer to the executable directly instead of relying on the PATH environment variable being set up correctly.
ExecStop= - This is the command that’s run when systemd attempts to stop this service; either automatically or when you run systemctl stop steam-workshop.service (or whatever you named the service). It’s the same steps in ExecStart but opposite and in reverse order: unmounting the virtual file system and destroying the loopback device. This allows systemd to cleanly shutdown and free those resources either during system shutdown or if you manually specify it on the command line. Without this step you may be stuck with leftover resources not cleaned up preventing you from remounting things.
RemainAfterExit=yes - This tells systemd that the service will exit after starting but to mark it as still active (as long as it ran the startup command successfully). This will cause systemd to report the status of this service correctly, as well as making sure the ExecStop command is run during shutdown. Without this command systemd would consider this service inactive after it finishes running ExecStart and wouldn’t run ExecStop later.
WantedBy=multi-user.target - This indicates to systemd when to run this script during boot up.

After creating the service, enable and start it with sudo systemctl enable --now steam-workshop.service. Now the virtual file system will be created and mounted automatically when the computer boots up, ready for Steam to use. Since it’s mounted in the directory Steam expects workspace content to be, any newly subscribed content will automatically be added to the virtual file system.

How To: Set up a reverse proxy

2026-03-16T00:00:00-07:00

Setting up external access to servers inside your home network is possible by setting up reverse tunnels behind a reverse proxy.

You will need an external server that is publicly accessible by the Internet. This server can serve any number of private servers inside your network via a reverse proxy. I personally use a basic DigitalOcean droplet that costs $6 per month. You don’t need a lot of power for this server, but you want something that won’t max out your bandwidth or CPU limits, as that will introduce a lot of latency to your SSH tunnels and ultimately your applications.

You will need to configure two components to enable access to your home network. First, set up the reverse tunnel to tunnel traffic from the remote server to the local server. Then, configure the reverse proxy on the remote server to direct traffic to the reverse tunnel.

Definitions

External/Remote server: This is the server that is running outside of your network and is publicly accessible from the Internet.
Local/Private server: This is a server running inside of your home network. You can have multiple local servers, in which you would follow these instructions for each tunnel on each server.
Reverse tunnel: This is an SSH tunnel that is established from the server that the traffic is being forwarded to. This is the opposite of a traditional tunnel which is initiated from the server sending the traffic, hence the name reverse tunnel. Reverse tunnels are useful when the destination of the traffic is inaccessible from the source of the traffic, such as a home network that has inbound traffic blocked by an ISP.
Reverse proxy: This is a web server that listens for HTTP/s traffic and redirects (i.e. proxies) that traffic to a different endpoint. In this setup, the reverse proxy helps isolate your network and tunnel from potentially dangerous traffic on the Internet. A traditional proxy is a web server that processes outbound traffic, hence why one that processes inbound traffic is called a reverse proxy.

Reverse SSH Tunnel

The reverse tunnel creates an SSH session to a remote machine and tunnels traffic from the remote machine to the local machine. You will need one reverse tunnel for each port you want to forward traffic to. You can have as many tunnels as you need from the same machine.

Setting up the reverse tunnel

Use the following ssh command from the local server to create the reverse ssh tunnel:

/usr/bin/ssh -N -o ServerAliveInterval=60 -o ServerAliveCountMax=3 -o ExitOnForwardFailure=yes -R <remote-listening-port>:<local-forwarding-server>:<local-forwarding-port> -i <path-to-private-key> <remote-username>@<remote-server>

-N: This option tells SSH not to set up a full shell session for this connection. This will only establish the SSH connection for the tunnel.
-o ServerAliveInterval=60: This option sends a keep-alive signal through the tunnel every 60 seconds. You may need this option if the tunnel is closed due to inactivity.
-o ServerAliveCountMax=3: This option tells the connection to terminate when 3 keep-alive signals are not responded to. This will automatically close the tunnel if the remote machine has disconnected or crashed without closing the connection. Without this option, the tunnel may stay open but unconnected and will need to be manually restarted in order to reconnect to the remote server. In addition, when used in a systemd service (covered in a later section), this allows the tunnel to automatically restart itself.
-o ExitOnForwardFailure=yes: This option tells SSH to exit with a failure if it can’t establish the connection. This allows it to automatically retry when inside of a systemd service.
-R <remote-listening-port>:<local-forwarding-server>:<local-forwarding-port>: This is the option for establishing the reverse tunnel. The tunnel will be set up to listen on port <remote-listening-port> on the remote server, and all traffic that arrives at that port will be forwarded to <local-forwarding-server> on port <local-forwarding-port> in your home network.

Note that by default, the remote port is bound to localhost, so it is not accessible to the Internet. You can choose to bind it to a public address by specifying a remote server address to bind to (for example, -R 0.0.0.0:<remote-listening-port>:<local-forwarding-server>:<local-forwarding-port> would allow any traffic to access the tunnel) but this is generally highly discouraged because you’re opening a direct connection from the Internet into your home network. There are bots constantly scanning the Internet for open ports to exploit, and then once an application is compromised they will move laterally inside your home network to compromise the rest of your devices. It’s recommended to keep the tunnels bound to localhost and run them behind a reverse proxy, which will be covered in the next section.
-i <path-to-private-key>: This option specifies the path to the private key file to use to authenticate the connection. You can use a different form of authentication if you want, for example username and password, but it’s highly recommended not to have your username or password hard coded, and key pair authentication is easier to use for unattended services.
<remote-username>@<remote-server>: Finally, this is the username and server (either IP address or domain name) of the remote server. The user should be a special user used just for your SSH tunnels and have all other permissions and logon rights disabled for security. Instruction on how to set this user up will be covered in a later section. However, you can also use just a regular logon user for this, it’s just less secure.

This is an example that I am currently using to create a tunnel from port 3001 on a public DigitalOcean droplet to an instance of Jellyfin running on the same machine on port 8096:

/usr/bin/ssh -N -o ServerAliveInterval=60 -o ServerAliveCountMax=3 -o ExitOnForwardFailure=yes -R 3001:localhost:8096 -i /home/sshtunnel/.ssh/tunnel_rsa sshtunnel@cloud.michaelhumphrey.dev

Creating a service for the tunnel

If you run the reverse tunnel from the command line, it will only stay running as long as the command is running. If you close the terminal it’s running in, the reverse tunnel will terminate. You can always start the command and run it in the background, but then you may not notice if the tunnel shuts down, and is difficult to restart. To fix these issues, you can configure a systemd service to manage the tunnel for you. Below is a template you can use to create the service:

[Unit]
Description=<service-name>
After=network-online.target

[Service]
User=<username>
ExecStart=/usr/bin/ssh -N -o ServerAliveInterval=60 -o ServerAliveCountMax=3 -o ExitOnForwardFailure=yes -R <remote-listening-port>:<local-forwarding-server>:<local-forwarding-port> -i <path-to-private-key> <remote-username>@<remote-server>

RestartSec=5
Restart=always

[Install]
WantedBy=multi-user.target

Description=<service-name>: A short description of this tunnel.
After=network-online.target: Wait to start this service until after the network is online.
User=<username>: The user this service should run under. Ideally this would be a user that is only used to run the SSH tunnels and have no other permissions and logon rights disabled, but it can also be a regular user. See the next section for instructions on how to set up a user for the tunnel.
ExecStart=<ssh-command>: This is the command to be run when this service is started. See the previous section for instruction on how to set up the ssh command.
RestartSec=5: This option specifies that if this service stops for any reason, it should wait 5 seconds before restarting. You can set this to whatever you like, but it should be short enough to minimize downtime if the tunnel can be reestablished and long enough to let the network connection shutdown and cleanup its resources before trying again. For less critical application, you can set this upward of 30-60 seconds or more to avoid straining your server if the remote server becomes unavailable for a period of time. Don’t set this to anything less than two seconds, otherwise the service may be terminated for starting up too many times too quickly.
Restart=always: This option specifies that the service should always start up after it stops for any reason. You can also set this option to on-failure to only start back up if it crashed.

Creating a user for the tunnel

To minimize the attack vector of exposing a tunnel to your home network from the Internet, it is recommended to set up a dedicated user with minimal permissions to run the tunnel. This ensures that even if that account is compromised, attackers still don’t have access to any other systems. You only need one user for all of your tunnels to use. In these examples, I’m using sshtunnel as the username, but you can use any username you prefer.

On the remote server

First, create the user and required directories on the remote server:

sudo useradd -m -s /usr/sbin/nologin sshtunnel
sudo mkdir -p /home/sshtunnel/.ssh

useradd: This command creates the user that the tunnel will run under.
-m: This option creates a home directory for the new user. We will use this directory to store the scripts for running the tunnel and symlinking them to the appropriate system directories.
-s /usr/sbin/nologin: This option sets the user’s login shell to /usr/sbin/nologin. This is a special shell that disallows this user from logging into the system, but lets it run system services and create tunnels. This prevents this user from being commandeered by an attacker while still allowing us to authenticate with a minimum-permission account for setting up the tunnel.
mkdir This command create the directory where the user’s ssh credentials will live.
-p: This option creates all parent directories for this directory if they don’t already exist.

Next, ensure that the directories belong to the user we created, not the currently logged in user or root:

sudo chown -R sshtunnel:sshtunnel ~/sshtunnel/.ssh
sudo chmod 700 ~/sshtunnel/.ssh
sudo chmod 600 ~/sshtunnel/.ssh/authorized_keys

chown -R sshtunnel:sshtunnel ~/sshtunnel/.ssh: This command recursively sets all files and directories in ~/sshtunnel/.ssh to belong to the sshtunnel user and group.
chmod ...: These commands set the permissions of the directory to the minimum necessary. The ssh keys for login are stored in these directories, so it’s important to keep them secure.

On the local server

Next, set up the reverse tunnels on the local server to use the newly created user.

First, create ssh key pair for authentication:

sudo mkdir -p /etc/sshtunnel
sudo ssh-keygen -qN "" -f /etc/sshtunnel/id_rsa

mkdir -p /etc/sshtunnel: This command creates a new directory for the tunnel credentials to live.
ssh-keygen: This command creates a new key pair for authentication.
-q: This option silences the output of the ssh-keygen command. It is optional.
-N "": This option sets the passphrase of the key pair to an empty string, essentially disabling the password requirement to use it. This makes it easier to allow the automated services to use it without prompting for a password. However, it makes it all the more important to keep these keys private, as anyone can use them to gain access to your system.
-f /etc/sshtunnel/id_rsa: This option specifies the newly created directory to store the key pair in.

Next, modify the systemd service files for the tunnels to use the new user. Most importantly, that means setting these ssh options:

-i /etc/sshtunnel/ssh: This points ssh to the private key we just created for the sshtunnel user.
sshtunnel@<remote-server>: Set the username when connecting to the remote server to sshtunnel.

Finally, copy the public key /etc/sshtunnel/id_rsa.pub to the remote machine and add it to the authorized keys file in ~/sshtunnel/.ssh/authorized_keys. This will allow the remote server to recognize and authenticate the newly created user. Make sure you connect to the remote server with the new credentials manually from the command line so you can whitelist the remote server’s public key as well.

Reverse Proxy

The other component needed is a reverse proxy to direct traffic from the Internet into the private SSH reverse tunnel you set up. The reverse proxy can do a lot of useful things for you, including providing a HTTPS endpoint in front of your services, load balancing, authentication, etc.

Configuring the reverse proxy

I use NGINX for my reverse proxy, but you can really do this part with any web server. The configuration options will be different, but the theory is the same.

Here is how I have my reverse proxy set up to terminate HTTPS connections and forward through the reverse SSH tunnel:

server {
    server_name <external-domain-name>;
    client_max_body_size 500M;  # Only needed if you're expecting large payloads

    location / {
        proxy_pass http://127.0.0.1:<reverse-tunnel-remote-port>;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate <path-to-fullchain.pem>; # managed by Certbot
    ssl_certificate_key <path-to-privkey.pem>; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

server {
    if ($host = <external-domain-name>) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    server_name <external-domain-name>;
    listen 80;
    return 404; # managed by Certbot
}

The second server block just redirects all HTTP requests for this domain to HTTPS. This makes it easier for any clients attempting to connect with HTTP first to be forced to use HTTPS. This block is automatically added when using the LetsEncrypt client.

The first server block handles all of the actual proxying.

server_name <external-domain-name>: This binds this server block to a particular domain. Different server blocks can be bound to different domains and ran simultaneously; NGINX will just check which domain a request is for and use the configs for the associated server block. If you don’t have this label, it will use it for all incoming requests, but then you would only be able to have one server block configuration for everything.
client_max_body_size 500M: By default NGINX limits incoming request payloads to 1 megabyte. This is fine for most applications, but if you need to set it to be larger (for example, Nextcloud or other backup solutions) you can use this option to set that limit higher. Note that sending excessively large payloads to overwhelm your server is a common denial-of-service attack and can result in exorbitant server expenses, so only use this option if you need it and set it to the lowest value that you actually expect to use.
location /: This block specifies the URL root. Setting the root to / will make this block handle all requests on the domain. You can specify a URL fragment if you want to run multiple services on the same domain. For example, you can have one service in a location /foo block and another service in a location /bar block, and then have different settings in each one. Then requests coming in at mydomain.com/foo will be sent to a different SSH tunnel than requests coming in to mydomain.com/bar.

While this configuration will allow NGINX to route subpath requests to different SSH tunnels, the applications running behind those tunnels will have to be configued to support such a configuration, as clients will still end the entire URL with the subpath in their HTTP requests. Not all applications support running on a subpath, so it’s up to you to decide which ones, if any, will run that way. I personally prefer to use subdomains to separate my services (e.g. foo.mydomain.com and bar.mydomain.com) as it’s easier and cleaner to support, but you do need full control over your domain to do so.
proxy_pass http://127.0.0.1:<reverse-tunnel-remote-port>: This option specifies where traffic in this block should be forwarded to. The 127.0.0.1 specifies it should be forwarded to the localhost, where the reverse tunnel is listening. <reverse-tunnel-remote-port> should be the same remote port you specified when setting up the reverse tunnel. We are connecting the reverse proxy to the tunnel here.
proxy_set_header ...: These configs are to properly pass request headers through the proxy to the application behind the proxy. Many services require these headers to be set properly, especially if you’re running security applications. Applications may not work, generate security errors, or report incorrect data if these are headers are not set correctly.
The remaining headers in the server block are to configure HTTPS. These should be automatically added when requesting a certificate through LetsEncrypt.

NGINX configuration files

The configuration for a reverse proxy should be saved with the filename that matches the domain it’s running on. For example, if your reverse proxy is running for the domain foobar.mydomain.com, then you would save the configuration in a file called foobar.mydomain.com. The directory for these configurations is by default /etc/nginx/sites-available. Then, when you’re finished editing the configuration file, create a symlink to the file in /etc/nginx/sites-enabled using the command :

ln -s <target-path> <link-name>

The target path is the full path to the file you want to symlink to (for example, /etc/nginx/sites-available/foobar.mydomain.com) and the link-name is the name you want the link to have (in most cases, it should be the same). When you are done, you can check the link by typing ls -l and you should see something like this:

lrwxrwxrwx 1 root root 45 Apr  6  2024 foobar.mydomain.com -> /etc/nginx/sites-available/foobar.mydomain.com

Once the symlink is created, your reverse proxy configuration is now ready to be used. First run the command nginx -t to test your configuration files. If there are any errors, fix them now. When the test returns successfully, you can reload the NGINX configs with the command systemctl reload nginx. Your reverse proxy is now live and directing HTTP traffic to your tunnel.

Alternatives to self-hosting

If you don’t have a publicly accessible server or don’t want to purchase a VPS (virtual public server) to host the external reverse proxy, there are other services that will do the equivalent of these steps for you. I have used Packet Riot in the past to forward traffic from the internet to my local network. Their free tier offers up to one tunnel, unlimited HTTP/s proxies for that tunnel, 1 TCP proxy for the tunnel, and up to 1 gigabyte of bandwidth per month. The next tier is only $5 / month and allows up to a terabyte of bandwidth. I like this service quite a bit, but ultimately had some intermittent issues that led me to pursue hosting my own reverse proxy since I already paid for a VPS.

Many self-hosters use ngrok as a reverse proxy for their services. It’s quite a bit more expensive but can handle almost everything for you. Tailwind is also a great option if you don’t need your services to be truly public, but want to access your services from your own devices from anywhere in the world. There’s countless other alternatives out there that will all do the same thing, but ultimately under the hood they function the same way as the tools described in this document.