# Applications

# 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](https://portall.boreux.work)  
🔲 Add the application to [homepage](https://home.boreux.work)  
🔲 Add the container to [Uptime Kuma](https://uptime.boreux.work)  
🔲 Add the container to [Guacamole](https://remote.boreux.work)

# Apache Guacamole

Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH.

# 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](https://bookstack.boreux.work/books/set-up/page/docker-installation-on-raspberry-pi-4-raspberrypi-os)


## Docker Compose Setup

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

<div class="callout info">I’m using the <a href="https://hub.docker.com/r/flcontainers/guacamole">flcontainers/guacamole</a> Docker image, which is compatible with the ARM64 architecture, unlike the official image.</div>

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

```yaml
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:

```bash
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

<div class="callout info">
<b>Username:</b> guacadmin<br>
<b>Password:</b> guacadmin
</div>

---

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

Happy me! 🌱

# Bookstack

BookStack is a simple, open-source, self-hosted, easy-to-use platform for organising and storing information.

# 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

Paperless-ngx is a document management system that transforms your physical documents into a searchable online archive.

# 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:

```bash
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:

```bash
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

Postgres is an open-source relational database management system.

# 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:

```yaml
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```sql
\l
\c <ANOTHER_DB_NAME>
```

## Step 3: Rename the Database

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

```sql
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:

```bash
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:

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

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

```bash
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:

```sql
ALTER USER <OLD_USER_NAME> RENAME TO <NEW_USER_NAME>;
```

---

Happy me! 🌱