Installing Talkyard

NOTICE: This Git branch is a PREVIEW of the upcoming Talkyard v1 (epoch 1).

You need to edit .env and set RELEASE_BRANCH=tyse-v1-dev (even though the comment juts above in .env says "don't use").

Do not use this preview of v1 "for real", in production, yet.

Also, don't install v0 — because then you'd want to upgrade to v1 pretty soon, a waste of time.

Instead: Wait 1 or 2 weeks until v1 has been released — that should be in the beginning of April 2026, or end of Mars. Then install v1.

Feedback welcome! You can post in: https://forum.talkyard.io

---

Here you'll learn how to install Talkyard v1 on a single server, for production use: Debian 12 or 13 with at least 2 GB RAM.

(Old Talkyard v0 docs are here.)

Docker-based installation. Automated upgrades and backups. Automatic HTTPS certs. Multi-site support.

You should be familiar with Linux, Bash, Git and Docker. Or use our hosting, see https://www.talkyard.io.

Ask questions and report problems in the forum.

Installation overview: You'll rent a virtual private server (VPS), download and install Talkyard, sign up for a send-emails service, and configure email settings. Then optionally configure OpenAuth login for Google, Facebook, Twitter, GitHub. And off-site backups.

Dockerfiles, build scripts and source code are in another repo: https://github.com/debiki/talkyard. See ./docker-compose.yml (in this repo) for details and links.

Directories

You'll install Talkyard in /opt/talkyard-v1/.

Talkyard uses these directories: (following the Linux File System Hierarchy Standard)

• /opt/talkyard-v1/: Various scripts, and docker-compose.yml. This is a Git repo — you can check in your changes to Git, but only if you can resolve Git conflicts!
• /opt/talkyard-v1/conf: Configuration, mounted read-only in Docker containers.
• /opt/talkyard-v1/secrets: Docker secrets, e.g. database password.
• /var/lib/docker/: Database storage, uploaded files (in Docker volumes). Docker images, log files.
• /var/opt/backups/talkyard/v1/: Backups.

Preparations

1. Provision a Debian 12 or 13 server, or Ubuntu 24.04, with at least 20 GB disk and 2 GB RAM, for example at Upcloud.

   Point a domain name, say, forum.your-website.com, to the server IP address.

2. Update the OS, then install Git and some stuff:

   apt-get update
   apt-get upgrade
   apt-get -y install git locales
   apt-get -y install rng-tools        # better generation of random numbers
   apt-get -y install jq               # to view logs
   apt-get -y install tree ncdu vim    # nice to have
   locale-gen en_US.UTF-8              # installs English
   export LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8  # starts using English (warnings are harmless)
   

3. Create big empty files that you can delete if your server runs out of disk:

   fallocate --length 250MiB /balloon-1-delete-if-disk-full
   fallocate --length 250MiB /balloon-2-delete-if-disk-full
   fallocate --length 250MiB /var/balloon-3-delete-if-disk-full
   fallocate --length 250MiB /var/balloon-4-delete-if-disk-full
   

4. Install Docker. Read: https://docs.docker.com/engine/install/debian/ and follow the instructions. Or use their convenience script: https://docs.docker.com/engine/install/debian/#install-using-the-convenience-script.

   Afterwards, also install the Docker Compose plugin:

   sudo apt-get install docker-compose-plugin
   

   (Optionally, add: { "log-driver": "local" } to /etc/docker/daemon.json, so Docker will delete old logs for all your Docker containers, and save disk. But you don't need to — Talkyard uses that logging driver by default in any case.)

Advanced

If you want to, and know what you're doing:

Swap: Comment out any swap from /etc/fstab, and run: swapoff -a.

Disks: Mount /var/ and /var/opt/backups/(talkyard/) on their own disks (so the host OS and Talkyard won't stop working just because some disk gets full).

Firewall: Install a firewall, for example, firewalld, see: https://firewalld.org.

Note that ufw (another Linux firewall) is incompatible with Docker — Docker can bypass ufw rules, see: https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-and-ufw. There is, however, ufw-docker.

You can see the IP addresses of the Docker containers in the .env file. The IP of the web container, which runs Nginx and listens on ports 80 and 443, is set on the FE_PUB_NET_WEB_IP=... line, and this is the only container that should be reachable from outside. The egress proxy should be able to connect to the Internet (but no one should be able to connect to it). Its IP address is set on the EG_PUB_NET_EGRESSP_IP=... line. More about Firewalld and Docker: https://firewalld.org/2024/04/strictly-filtering-docker-containers

If you use Google Cloud Engine: GCE already has a firewall.

Installation instructions

(There's a troubleshooting document here: ./docs/troubleshooting.md )

1. Download installation scripts: (you need to install in /opt/talkyard-v1/ for the backup scripts to work)

   sudo -i  # become root
   cd /opt/
   git clone https://github.com/debiki/talkyard-prod-one.git talkyard-v1
   cd talkyard-v1
   # Make sure you'll install v1:
   git checkout --track origin/ty-prod-one-v1
   

2. Prepare the OS: install tools, enable automatic security updates, simplify troubleshooting, and make ElasticSearch work: (Consider reading the script first...)

   ./scripts/prepare-os.sh 2>&1 | tee -a talkyard-maint.log
   

   If you don't want to run the whole script, you at least need to:

   • Copy the sysctl net.core.somaxconn and vm.max_map_count settings in the script to your /etc/sysctl.conf config file — otherwise, the full-text-search-engine (ElasticSearch) won't work. Afterwards, run sysctl --system to reload the system configuration.

3. Edit config values:

   nano conf/app/play-framework.conf   # fill in values in the Required Settings section
   
   nano secrets/postgres_password.txt  # type a database password on a single line, nothing else!
   
   # Don't let anyone see the password.
   chmod 0600 secrets/postgres_password.txt
   

   Note:

   • Set talkyard.secure=true, so HTTPS will work — unless you're testing on localhost; then set talkyard.secure=false.
   • If you don't edit play.http.secret.key in play-framework.conf, the server won't start.
   • A PostgreSQL database user, named talkyard, gets created automatically, by the rdb Docker container, with the password you specified in secrets/postgres_password.txt. You don't need to do anything.

4. Depending on how much RAM your server has (run free -mh to find out), choose one of these files: mem/1.7g.yml, mem/2g.yml, mem/3.6g.yml, ... and so on, and copy it to ./docker-compose.override.yml. For example, for a server with 4 GB RAM:

    cp mem/4g.yml docker-compose.override.yml
   

5. Install and start the latest version. Might take a few minutes the first time (to download Docker images).

    # This script also installs, although named "upgrade–...".
    ./scripts/upgrade-if-needed.sh 2>&1 | tee -a talkyard-maint.log
   

   (This creates a new Docker network — you can choose the IP range; see the section Docker Networks below.)

   Type docker compose ps — you should now see a list of Docker containers in state Up (means they're running).

6. Schedule daily backups, deletion of old backups, and automatic upgrades:

    ./scripts/schedule-daily-backups.sh 2>&1 | tee -a talkyard-maint.log
    ./scripts/schedule-automatic-upgrades.sh 2>&1 | tee -a talkyard-maint.log
   

7. Open a web browser; go to https://talkyard.your website.com — note: https not http.

   Your browser should show a warning about the connection not being secure. Talkyard and LetsEncrypt will now start generating a HTTPS certificate for you. Wait 20 seconds, reload the page, and thereafter HTTPS should work.

8. In the browser, click Continue and create an admin account with the email address you specified when you edited play-framework.conf earlier (see above). Follow the getting-started guide.

Everything will restart automatically on server reboot.

Next steps:

• Edit /opt/talkyard-v1/conf/web/sites-enabled/talkyard-servers.conf and redirect from HTTP to HTTPS.
  
• Sign up for a send-email-service — see the section just below.
• Send an email to hello at talkyard.io so we get your address, and can inform you about security issues and major software upgrades that might require you to do something manually. Or subscribe to the Announcements category over at https://www.talkyard.io/forum/.
• Copy backups off-site, regularly. See the Backups section below.
• Configure Gmail, Facebook, Twitter, GitHub login, by creating OpenAuth apps over at their sites, and adding API keys and secrets to play-framework.conf. See below, just after the next section, about email.
• Optionally, create more Talkyard sites hosted by this same Talkyard installation, see docs/multisite-talkyard.adoc.

Configuring email

If you don't have a mail server already, then sign up for a transactional email service, for example Mailgun, Elastic Email, SendGrid, Mailjet or Amazon SES. (Signing up, and verifying your sender email address and domain, is a bit complicated — nothing you do in five minutes.)

Then, configure email settings in /opt/talkyard/conf/play-framework.conf, that is, fill in these values:

talkyard.smtp.host="..."
talkyard.smtp.port="587"
talkyard.smtp.requireStartTls=true
#talkyard.smtp.tlsPort="465"
#talkyard.smtp.connectWithTls=true
talkyard.smtp.checkServerIdentity=true
talkyard.smtp.user="..."
talkyard.smtp.password="..."
talkyard.smtp.fromAddress="support@your-organization.com"

(Google Cloud Engine blocks outgoing ports 587 and 465 (at least it did in the past). Probably you email provider has made other ports available for you to use, e.g. Amazon SES: ports 2587 and 2465.)

OpenAuth login

You want login with Facebook, Gmail and maybe Twitter and GitHub to work? Here's how.

However, we haven't written easy to follow instructions for this yet. Send us an email: hello at talkyard.io, mention OpenAuth, and we'll hurry up.

(There are very very brief instructions in this the markdown source but they might be out of date, or there might be typos, so they're hidden unless you are a tech person who knows how to view the source.)

Viewing log files

Change directory to /opt/talkyard-v1/. Then:

• The application server, to view its logs: ./view-logs -f --tail 50 app   (where -f --tail NN is optional). You can also: docker compose logs -f --tail 50 app, but then you'll see hard to read json. view-logs uses jq to parse & make readable the json.
• The web server: docker compose logs -f --tail 50 web (not json).
• The database: docker compose logs -f --tail 50 rdb (not json).
• The search engine: ./view-logs search.

Upgrading to newer versions

If you followed the instructions above — that is, if you ran these scripts: ./scripts/prepare-os.sh and ./scripts/schedule-automatic-upgrades.sh — then your server should keep itself up-to-date, and ought to require no maintenance.

In a few cases you might have to do something manually, when upgrading. Like, running git pull and editing config files, maybe running a shell script. For us to be able to tell you about this, please send us an email at hello at talkyard.io.

If you didn't run ./scripts/schedule-automatic-upgrades.sh, you can upgrade manually like so:

sudo -i
cd /opt/talkyard-v1/
./scripts/upgrade-if-needed.sh 2>&1 | tee -a talkyard-maint.log

Backups

Importing a backup

See docs/how-restore-backups.md.

You can log in to Postgres like so:

sudo docker compose exec rdb psql postgres postgres  # as user 'postgres'
sudo docker compose exec rdb psql talkyard talkyard  # as user 'talkyard'

Backing up, manually

You should have configured automatic backups already, see the Installation Instructions section above. In any case, you can backup manually like so:

sudo -i
cd /opt/talkyard-v1/
./scripts/backup.sh manual 2>&1 | tee -a talkyard-maint.log

New backups should appear in /var/opt/backups/talkyard/v1/archives/.

Copy backups elsewhere

You should copy the backups to a safety off-site backup server, regularly. Otherwise, if your main server suddenly disappears, or someone breaks into it and ransomware-encrypts everything — you'd lose all data.

See docs/copy-backups-elsewhere.md.

Docker networks

Talkyard creates its own Docker subnets, for security reasons, and assigns static IPs to the containers. Without static IPs, then, if a container restarts, Docker might give it a new IP, and the other containers then couldn't find it it. — Unless they're also restarted, so all things that have cached the old stale IP, pick up the new IP instead.

You can choose the network IP ranges. Open the .env file, scroll down and you'll see:

FE_PUB_NET_SUBNET=...
FE_INT_NET_SUBNET=...
BE_INT_NET_SUBNET=...
...

Tips

If you start running out of disk, one reason can be old patches for automatic operating system security updates. You can delete them to free up disk:

sudo apt autoremove --purge

License (MIT)

Copyright (c) 2016-2025 Kaj Magnus Lindberg.

Licensed under the MIT license, see `LICENSE-MIT.txt` — and this is for the
instructions and scripts in this repository only, not for Talkyard source code
or things in other repositories.