Applications

• Deployment Checklist
• Apache Guacamole
• Docker Installation on ARM64
• Bookstack
• Changing the Base URL
• Paperless-ngx
• Backup & Restore
• PostgreSQL
• Major Upgrade
• Renaming a Database
• Renaming a Role (User)

Deployment Checklist

Here is a checklist to make sure to not forget anything when deploying a new container on my Docker.

---

🔲 Create a CNAME record on Cloudflare
🔲 Create a CNAME record on PiHole
🔲 Write the compose.yaml and .env files
🔲 Add the container to the Caddyfile
🔲 Add the container port to Portall
🔲 Add the application to homepage
🔲 Add the container to Uptime Kuma
🔲 Add the container to Guacamole

Apache Guacamole

Docker Installation on ARM64

Apache Guacamole is a powerful tool for managing remote connections, and installing it on a Raspberry Pi 4 with Docker allows for easy, remote access from almost anywhere

---

Prerequisites

1. Raspberry Pi 4
2. Docker installed

Docker Compose Setup

For this installation, we will use a compose.yaml file with Docker Compose to manage the Guacamole installation.

Here’s what the compose.yaml file should look like:

services:
    guacamole_app:
        container_name: guacamole_app
        image: flcontainers/guacamole:latest
        restart: unless-stopped
        ports:
            - 8094:8080
        volumes:
            - guacamole_app-config:/config
            - /etc/localtime:/etc/localtime:ro
        environment:
            TZ: 'Europe/Brussels'
        healthcheck:
            test: curl -f -k http://127.0.0.1:8080/ || exit 1
            interval: 15s
            timeout: 10s
            retries: 5

volumes:
    guacamole_app-config:
        name: guacamole_app-config

Installation

Once you’ve created the compose.yaml file, navigate to the directory where it’s stored and run the following command:

docker compose up -d

This command will pull the Guacamole image and install it on your Raspberry Pi.

Using Apache Guacamole

After the installation, you can access the Guacamole web interface by visiting http://<YOUR_RPI_IP>:8094

---

With this setup, you now have Apache Guacamole running on your Raspberry Pi 4, allowing easy remote desktop access and management.

Happy me! 🌱

Bookstack

Changing the Base URL

Sometimes, you need to change the base URL of Bookstack, for example, when you switch from the localhost address to the internet exposed address.

---

Docker Compose

In your compose.yaml, modify the following environment variable:

APP_URL=<new_url>

Bookstack Container

Open a terminal and type:

docker exec -it <bookstack_container> php /app/www/artisan bookstack:update-url <old_url> <new_url>

Clear Cache

Open a terminal and type:

docker exec -it <bookstack_container>  php /app/www/artisan cache:clear

Paperless-ngx

Backup & Restore

Here is the procedure to backup and restore the Paperless-NGX application and all of its data.

---

Backup

On a terminal, enter the following command:

docker compose exec -T <paperless_webserver> document_exporter -z ../export

Where:

• -T is used to suppress "The input device is not a TTY" error ;
• -z is used to zip the export ;
• ../export is used because this path inside the container is automatically mounted on your host on the folder export.

Restore

You'll need to unzip the previous export!

On a terminal, enter the following command:

docker compose exec -T <paperless_webserver> document_importer ../export/<unzipped_directory>/

Where:

• -T is used to suppres "The device is not a TTY" error ;
• ../export/<unzipped_directory>/ is the path to your previous backup unzipped.

PostgreSQL

Major Upgrade

How to Upgrade a PostgreSQL database inside a Docker Container: A Step-by-Step Guide

Step 1: Backup the Database

Before upgrading, it's essential to back up your database to avoid data loss.

1. Update compose.yaml to Add Volumes:

In your compose.yaml file, add the necessary volumes for data and backups:

postgres:
    ...
    volumes:
        - data:/var/lib/postgresql/data
        - backup:/backup
    ...

2. Shutdown All Containers Except the Database:

Stop all your stack's containers except for the PostgreSQL container.

3. Dump the Database into the Backup Directory:

Run the following command to export all SQL tables into a dump file:

docker exec -it <DB_CONTAINER_NAME> pg_dumpall -U <POSTGRES_USER> > /backup/dump.sql

Step 2: Clean Up the Existing Stack

1. Stop the Database Container:

Bring down the PostgreSQL container:

docker compose down <DB_CONTAINER_NAME>

2. Delete the Existing data Volume:

To prepare for the upgrade, remove the current data volume associated with PostgreSQL.

Step 3: Upgrade PostgreSQL

1. Update the PostgreSQL Version:

In the compose.yaml file, change the PostgreSQL image to the new version.

2. Bring Up the Updated PostgreSQL Container:

Run the following command to start the new version:

docker compose up -d

Step 4: Clear the New Data Volume

1. Stop All Stack Containers:

Ensure all containers are stopped to avoid any conflicts.

2. Delete Data Files in the Volume:

Navigate to the PostgreSQL volume and remove the data files located in /var/lib/docker/<DB_CONTAINER_NAME>/_data.

Step 5: Restore the Database

1. Start the Database Container:

Power on the PostgreSQL container.

2. Import the Data from Backup:

Use the following command to restore the dumped SQL data into the new PostgreSQL container:

docker exec -it <DB_CONTAINER_NAME> psql -U <POSTGRES_USER> -d <POSTGRES_DATABASE_NAME> < /backup/dump.sql

Final Step: Bring the Stack Back Online

Once the database has been restored, you can start all your other containers again.

And that's it! 🎉 You've successfully upgraded PostgreSQL in your Docker environment.

---

Happy me! 🌱

Renaming a Database

Renaming a PostgreSQL Database Inside a Docker Container: Step-by-Step Guide

Step 1: Connect to the PostgreSQL Server

To start, connect to the PostgreSQL server within the Docker container by running the following command:

docker exec -it <POSTGRESQL_CONTAINER_NAME> psql -U <POSTGRESQL_USERNAME>

Step 2: Switch to a Different Database

⛔️ When you connect to the PostgreSQL server, you’re likely accessing the database you want to rename. However, PostgreSQL doesn’t allow renaming a database while you’re connected to it.

✅ The Fix: Connect to a Different Database

To proceed, list all available databases on the server, then connect to another one:

\l
\c <ANOTHER_DB_NAME>

Step 3: Rename the Database

Now you can rename your database using the ALTER DATABASE...RENAME TO command:

ALTER DATABASE <OLD_DB_NAME> RENAME TO <NEW_DB_NAME>;

---

Happy me! 🌱

Renaming a Role (User)

Renaming a PostgreSQL Role Inside a Docker Container: Step-by-Step Guide

Step 1: Connect to the PostgreSQL Server

To start, connect to the PostgreSQL server within the Docker container by running the following command:

docker exec -it <POSTGRESQL_CONTAINER_NAME> psql -U <POSTGRESQL_USERNAME>

Step 2: Switch to a Different Role

⛔️ When you connect to the PostgreSQL server, you’re likely accessing the database with the user you want to rename. However, PostgreSQL doesn’t allow renaming a user while you’re connected to it.

✅ The Fix: Create and Connect with a Different Role

To proceed, enter the following command:

CREATE ROLE <NEW_USER> SUPERUSER LOGIN PASSWORD '<USER_PASSWORD>';

Disconnect from the server with the \q command then reconnect with the <NEW_USER> created:

docker exec -it <POSTGRESQL_CONTAINER_NAME> psql -U <NEW_USERNAME>

Step 3: Rename the Role

Now you can rename your role using the ALTER USER...RENAME TO command:

ALTER USER <OLD_USER_NAME> RENAME TO <NEW_USER_NAME>;

---

Happy me! 🌱