English
The droplet
How to read the commands of this module
Commands in powershell blocks run on your computer, as before. Commands in bash blocks run on the server, in the SSH session, as root. They are taken from Docs/Deployment.md; <your domain>, <droplet ip> and similar placeholders are replaced by your values, without the angle brackets. Each check box says what you should see on your server.
Step 1. One machine for everything
Why. Chatex in production consists of three programs: Nginx in front, the API behind it and PostgreSQL behind the API. Large systems put each on its own machines, behind load balancers, with a managed database. Chatex runs all three on one small virtual server, for three reasons:
- it is enough: the server only runs the application, all builds happen on GitHub's runners, and 1–2 GB of memory serve a lot of chat users;
- it is simple: one machine to set up, update and understand, and no network between the API and the database;
- it must be one copy of the API anyway: the online status of topic 14 lives in the memory of the API process, so two copies would disagree about who is online.
Only two kinds of traffic reach the machine from outside (Table 23.1): visitors on the web ports, and the administrator — later also the deploy workflow — over SSH. The API and PostgreSQL listen only on the loopback address 127.0.0.1 and are invisible from the internet.
Table 23.1. Programs and ports on the server
| Program | Listens on | Reachable from |
|---|---|---|
sshd | port 22 | the internet: you and GitHub Actions, with keys only |
| Nginx | ports 80 and 443 | the internet: users' browsers |
chatex-api (Kestrel) | 127.0.0.1:5000 | only Nginx and the activation script on the same machine |
| PostgreSQL | localhost:5432 | only the API, the migration bundle and psql on the same machine |
Step 2. An SSH key and the droplet
Why. A server on the internet receives password-guessing attempts within minutes of its creation. Logging in with an SSH key instead of a password makes guessing pointless: the private key never leaves your computer, and the server stores only the public half. DigitalOcean puts the public key into /root/.ssh/authorized_keys when it creates the droplet.
Do. Create a key pair on your computer, if you do not have one yet. Accept the default file and set a passphrase, which protects the key if somebody copies the file:
powershell
ssh-keygen -t ed25519The public key is the file id_ed25519.pub in the folder .ssh of your user profile. Then, in the DigitalOcean control panel, Create → Droplets:
- Image: Ubuntu 26.04 (LTS) x64;
- Size: a basic droplet with 1 GB or 2 GB of memory;
- Region: a data centre close to your users;
- Authentication: SSH Key, New SSH Key, and paste the content of
id_ed25519.pub.
When the droplet is ready, copy its public IPv4 address and log in:
powershell
ssh root@<droplet ip>The first connection asks whether you trust the server's host key (Are you sure you want to continue connecting (yes/no/[fingerprint])?); answer yes. The key is remembered in your known_hosts file, and a different key at the same address later would be reported as a possible attack.
Check
The prompt changes to root@<droplet name>:~#. Ask the server which system it runs:
bash
cat /etc/os-releaseThe first line is PRETTY_NAME="Ubuntu 26.04.1 LTS" (or a later point release).
A learning setup: everything as root
Like Docs/Deployment.md, this module administers the server as root over SSH, and the deploy workflow of topic 24 connects as root too. It keeps the number of moving parts small, and the dangerous part — the application — already runs as an unprivileged user in a sandbox. A production team would go further: personal administrator accounts that use sudo, root login over SSH switched off, and a separate deploy user that is allowed to run exactly one command, chatex-activate, through sudo (the header of activate-release.sh in topic 24 is written for that case). Exercise 3 of the checkpoint asks you to plan it.
Step 3. A DNS record
Why. Browsers reach the site by name, and the certificate at the end of this topic is issued for a name, after Let's Encrypt has checked that the name points at this server. DNS changes need minutes or sometimes hours to spread, so we create the record now and use it at the end.
Do. At the provider that manages your domain, create an A record: the name is the subdomain you want (for example chatex, giving chatex.<your domain>), the value is the droplet's IPv4 address. The reference uses chatex.mvano.com. In the rest of the module, <your domain> means this full name.
Check
On your computer:
powershell
nslookup <your domain>The answer lists the droplet's IP address under Address. If it says Non-existent domain, wait a few minutes and try again.
Step 4. The packages
Why. The server needs the programs of Table 23.1 and a few tools — but not the .NET SDK or Node.js: the release that arrives in topic 24 is already built. Every package comes from Ubuntu's own archive, which Ubuntu updates with security fixes; Ubuntu 26.04 ships .NET 10 and PostgreSQL 18 directly, so no extra package sources are needed.
Do. One command installs everything:
bash
apt update && apt install -y aspnetcore-runtime-10.0 postgresql nginx certbot python3-certbot-nginx ufw rsync curlaspnetcore-runtime-10.0— the ASP.NET Core runtime with thedotnethost, enough to runChatex.Api.dll. The SDK, which compiles, would be ten times larger and a bigger attack surface.postgresql— the database server; the package creates and starts a cluster that listens only onlocalhost.nginx— the web server and reverse proxy.certbot,python3-certbot-nginx— the Let's Encrypt client and its plugin that edits the Nginx configuration.ufw— the "uncomplicated firewall", a front end for the Linux packet filter.rsync— receives the release from GitHub Actions in topic 24.curl— an HTTP client for the health checks.
-y answers "yes" to the confirmation, so the command runs without questions.
Check
bash
dotnet --list-runtimesMicrosoft.AspNetCore.App 10.0.15 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 10.0.15 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]The patch number may be higher. nginx -v prints nginx version: nginx/1.28.3 (Ubuntu) and psql --version prints psql (PostgreSQL) 18.6 …, or later patch versions.
Security updates
Ubuntu server images install and enable unattended-upgrades, which applies security updates of the Ubuntu archive every day. The packages installed above therefore receive their fixes automatically. Check that the service is active with systemctl status unattended-upgrades, and look at /var/log/unattended-upgrades/ from time to time. Updates of the kernel take effect only after a reboot; the login message says when one is required.
Step 5. The firewall
Why. Right now every program that opens a port is reachable from the internet. A firewall turns this around: everything is blocked except what we allow on purpose — SSH, HTTP and HTTPS. Then a service that accidentally listens on a public address, or a forgotten test server, stays invisible.
Do.
bash
ufw allow OpenSSH && ufw allow 'Nginx Full' && ufw enableOpenSSHandNginx Fullare application profiles that the packages install (ufw app listshows them): port 22, and ports 80 and 443.- The order matters.
ufw enablestarts blocking at once. Had SSH not been allowed first, your session would freeze and you would need the provider's web console to get back in.ufwasksCommand may disrupt existing ssh connections. Proceed with operation (y|n)?; answery.
Check
bash
ufw statusStatus: active
To Action From
-- ------ ----
OpenSSH ALLOW Anywhere
Nginx Full ALLOW Anywhere
OpenSSH (v6) ALLOW Anywhere (v6)
Nginx Full (v6) ALLOW Anywhere (v6)The firewall stays active after a reboot (Firewall is active and enabled on system startup).
Cloud firewalls
Some providers have their own firewall in front of the machine (DigitalOcean calls it Cloud Firewalls). It is off by default. If you turn it on, allow the same three ports there, or the browser and GitHub cannot reach the server even though ufw allows them.
Step 6. A copy of the repository
Why. The server files of the next chapters — the settings template, the systemd unit, the Nginx site — are written in the repository, reviewed like code, and copied to the server from a clone. Then the files in the repository and on the server cannot silently diverge, and a new server is set up from the same files.
Do. Clone your repository into the home folder of root and change into it:
bash
git clone <your repository url> chatex && cd chatexThe repository is private, so Git asks for a user name and a password. GitHub does not accept account passwords here: create a fine-grained personal access token on GitHub (Settings → Developer settings → Personal access tokens) with read-only access to the contents of this one repository, and paste it as the password.
The files of this topic are committed to dev, so switch to that branch:
bash
git switch devFrom now on, each chapter writes its files on your computer, commits and pushes them to dev, and fetches them on the server with:
bash
git pullGit asks for the token again on every git pull; keep it in your password manager until the server is set up.
Check
bash
git statusThe output starts with On branch dev and Your branch is up to date with 'origin/dev'.