Skip to main content

Listmonk

We have a Listmonk instance running providing us with a newsletter service. You can access it here.

Access​

User access To get access to listmonk you need an @acemate.ai email address. If you don't have one, please reach out to the team. Currently everyone has access to the listmonk instance.

Programmatc Access To use the API of listmonk to sent for example sent transactional mails, another authentication method is implemented using basic auth. The username and password is provided to Jan Tiegges. The authentication data can be used in a standard authentication basic auth header:

Authorization: Basic <base64 encoded username:password>
info

The username and password needs to be base64 encoded as username:password. You can do that in a linux terminal:

echo -n "username:password" | base64

Server Information​

  • Server: Hetzner
  • IP Address: 195.201.232.103
  • SSH Access: ssh root@195.201.232.103 or ssh -i /path/to/your/key root@195.201.232.103
tip

You can specify which SSH key to use with the -i flag:

ssh -i ~/.ssh/your_private_key root@195.201.232.103

This is useful if you have multiple SSH keys or don't use the default ~/.ssh/id_rsa location.

SSH Access and Key Management​

To access the server, you need to add your SSH key. Here's how to do it:

  1. Generate an SSH key (if you don't already have one):

    ssh-keygen -t rsa -b 4096

  2. Add your key to the server:

    There are two ways to add your SSH key to the server:

    a) Through the Hetzner Control Panel:

    • Log in to the Hetzner Control Panel
    • Navigate to the server settings
    • Add your public key to the authorized keys section

    b) If you already have access to the server, you can add another user's key:

    # On the server
    echo "ssh-rsa AAAA..." >> ~/.ssh/authorized_keys

    Replace ssh-rsa AAAA... with the actual public key content.

  3. Connect to the server:

    Once your key is added, you can connect using:

    # Basic connection
    ssh root@195.201.232.103

    # If you need to specify your key location
    ssh -i /path/to/your/private_key root@195.201.232.103
info

Ask a team member with existing server access to add your key if you don't have access to the Hetzner Control Panel.

Deployment Overview​

This Listmonk instance is deployed using Docker and Docker Compose. The main components are:

  1. Listmonk Application: The main email newsletter manager application
  2. PostgreSQL Database: Stores all subscriber data, campaigns, and settings

Repository Structure​

In our codebase, the following files manage the Listmonk deployment:

  • services/listmonk/config.toml: Main configuration file for Listmonk (with password placeholders)
  • services/listmonk/docker-compose.yml: Docker Compose configuration for running the service (with password placeholders)
  • services/listmonk/.env: Contains the actual password values (not committed to Git)
  • services/listmonk/backups/: Contains database backups
  • services/listmonk/scripts/: Utility scripts for managing the deployment

Environment Setup​

  1. Create a .env file in the services/listmonk directory with the following content:
DB_PASSWORD=your_actual_db_password
  1. Replace the placeholder values with the actual password.

Managing the Deployment​

We have different scripts for different operations:

ScriptPurpose
deploy.shDeploy configuration changes (passwords, settings)
backup.shCreate a backup of the database
restore.shRestore from a backup

Deploying Configuration Changes​

Use the deploy script when you need to update configuration files (config.toml, docker-compose.yml):

cd services/listmonk
./scripts/deploy.sh

If you need to use a specific SSH key:

cd services/listmonk
SSH_KEY=/path/to/your/ssh/key ./scripts/deploy.sh

This script will:

  1. Read password value from your .env file
  2. Replace placeholder in configuration files with actual value
  3. Upload the processed files to the server
  4. Restart the Listmonk service

Creating a Backup​

The backup.sh script can be used to create and download a backup:

cd services/listmonk
./scripts/backup.sh

# With custom SSH key
SSH_KEY=/path/to/your/ssh/key ./scripts/backup.sh

Restoring a Backup​

To restore from a backup:

cd services/listmonk
./scripts/restore.sh backups/your-backup-file.tar.gz

# With custom SSH key
SSH_KEY=/path/to/your/ssh/key ./scripts/restore.sh backups/your-backup-file.tar.gz

Viewing Logs​

ssh root@195.201.232.103
cd /root/listmonk
docker-compose logs -f

# If you need to specify your SSH key
ssh -i /path/to/your/ssh/key root@195.201.232.103
cd /root/listmonk
docker-compose logs -f

Server Setup​

When logged in via SSH, you can find the folder listmonk in the root directory. This folder contains the config.toml, docker-compose.yml, and any backups.

Secure Proxy (caddy)​

As listmonk is only supporting basic auth (which is insecure), a secure proxy was added using caddy.

Caddy is a web server which is used to put an authentication proxy in front of listmonk. This enabled the Google oauth login for listmonk. The caddy version installed in this system is modified using xcaddy. Xcaddy was used to install the plugin caddy-security. The caddy configuration is located in /etc/caddy/Caddyfile. Additionally caddy is run using a system deamon which is located in /etc/systemd/system/caddy.service. The caddy binary is located in /usr/bin/caddy.

Google Cloud Console​

In the Google Cloud Organisation of acemate, a project named listmonk is created. This project is just there to manage the OAuth credentials for listmonk. The OAuth credentials are configured in the APIs & Services -> Credentials section of the project.

DNS (Cloudflare)​

The DNS records for pointing to the listmonk server are managed in Cloudflare. The domain listmonk.acemate.ai is pointing to the Hetzner server. Additionally the domain auth-listmonk.acemate.ai is pointing to the caddy server, but is not used anymore.