Improve how to deploy a collection

Author: Ndpnt

content/deployment/how-to/deploy.md

@@ -7,44 +7,67 @@ weight: 1
 
 This guide will help you deploy an Open Terms Archive collection to a server.
 
+> **Note**: This guide is intended for both Open Terms Archive organization members and external contributors. Some steps marked with [🔒 **Specific to Open Terms Archive organization members**] are only relevant for organization members as they involve access to the organization's shared password database. External contributors should adapt these steps to their own security practices while following the same deployment principles.
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- A server with admin access
+- All collections repositories created, if not, see the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}}).
+- A GitHub user account dedicated to bot-related actions (commit entries in versions and snapshots repositories, report issues when tracking fails, publish releases, …)
+
 ## 1. Configure the server
 
 First, ensure your server provides unsupervised access:
 
-1. Check the SSH host key:
+1. Check the SSH host key and get the SSH fingerprint by running the following command on your local machine:
+
    ```shell
-   ssh-keyscan --type=ed25519 <server_address>
+   ssh-keyscan -t ed25519 <server_address>
    ```
-   If no Ed25519 key appears, generate one on the server:
+
+   If no Ed25519 key appears, generate one by running the following commands on the server:
+
    ```shell
-   sudo ssh-keygen --type=ed25519 --file=/etc/ssh/ssh_host_ed25519_key
+   sudo ssh-keygen -t ed25519 --file=/etc/ssh/ssh_host_ed25519_key
    sudo systemctl restart ssh
    ```
 
-2. Create a non-root user if needed:
+   > **Note**: A server fingerprint is a unique identifier for your server's SSH key. It helps verify that you're connecting to the correct server and not a malicious one. The fingerprint is a hash of the server's public key and is used to prevent man-in-the-middle attacks. You'll need this fingerprint in the next steps for secure deployment.
+
+2. Create a dedicated user account specifically for deployment purposes, by running the following commands on the server:
+
    ```shell
    adduser <user>
    usermod --append --groups=sudo <user>
    ```
 
-3. Grant passwordless sudo access:
+   > **Note**: The `adduser` command might not be installed by default on your system. It can be installed with `sudo apt-get install adduser`.
+
+3. Configure sudo access for this user, by running the following command on the server:
+
    ```shell
    # Add to /etc/sudoers:
    <user> ALL=(ALL) NOPASSWD:ALL
    ```
 
+   > **Note**: While passwordless sudo access does reduce security compared to requiring a password, it is essential for full automation in deployment workflows with Ansible. The deployment process requires system-level operations (like installing packages and configuring services) that must be executed without manual intervention. To mitigate security risks, this configuration is limited to a dedicated deployment user that should only be used for deployment purposes, and the server must be properly secured with SSH key authentication.
+
 ## 2. Set up the deployment configuration
 
 1. Clone the collection declarations repository:
+
    ```shell
    git clone https://github.com/OpenTermsArchive/<collection_id>-declarations.git
    ```
 
-2. Configure the inventory file `deployment/inventory.yml`:
+2. Configure the inventory file `deployment/inventory.yml` with your server's IP address, deployment user (from step 1), and server fingerprint (from step 1):
+
    ```yaml
-   <host>: "your.server.ip"
-   ansible_user: "your_username"
-   ed25519_fingerprint: "your_ssh_fingerprint"
+   <host>: "server_ip"
+   ansible_user: "deployment_user"
+   ed25519_fingerprint: "server_ssh_fingerprint"
    ```
 
 3. Add the server fingerprint to GitHub:
@@ -53,7 +76,8 @@ First, ensure your server provides unsupervised access:
 
 ## 3. Configure SSH deployment keys
 
-1. On the server, generate a deployment key:
+1. On the server, generate a deployment key, which will be used by the continuous deployment workflow to deploy the collection:
+
    ```shell
    ssh-keygen --type=ed25519 --quiet --passphrase="" --file=~/.ssh/ota-deploy
    cat ~/.ssh/ota-deploy.pub >> ~/.ssh/authorized_keys
@@ -63,19 +87,19 @@ First, ensure your server provides unsupervised access:
    - Go to the repository secrets
    - Create `SERVER_SSH_KEY` with the private key content
 
-3. Back up the keys:
-   - Store both public and private keys in the shared password database
-   - Create an entry titled "Deployment SSH key" in the collection folder
+3. [🔒 **Specific to Open Terms Archive organization members**] Back up the keys in the shared password database:
+   - Create an entry titled "Deployment SSH Key" in the collection folder
+   - Store both public and private keys in this entry
 
-## 4. Set up GitHub permissions
+## 4. Set up GitHub permissions for bot user
 
 1. Create a fine-grained GitHub token:
    - Log in as OTA-Bot
    - Create a new token at github.com/settings/personal-access-tokens/new
    - Set repository access for both declarations and versions repos
    - Grant "Contents" and "Issues" write permissions
 
-2. Back up the token:
+2. [🔒 **Specific to Open Terms Archive organization members**] Back up the token:
    - Store it in the shared password database under "GitHub Token"
 
 3. Get the token approved:
@@ -85,29 +109,36 @@ First, ensure your server provides unsupervised access:
 
 1. Generate and store a vault key:
    - Generate a secure password without quotes/backticks
-   - Store it in the password database
    - Create `deployment/vault.key` with the password
    - Add it as `ANSIBLE_VAULT_KEY` in GitHub secrets
 
-2. Store GitHub token:
-   ```
+2. Store GitHub token (from step 4):
+
+   ```shell
    # In deployment/.env:
    OTA_ENGINE_GITHUB_TOKEN=your_token
    ```
 
 3. Encrypt the `.env` file:
+
    ```shell
    ansible-vault encrypt .env
    ```
 
+4. [🔒 **Specific to Open Terms Archive organization members**] Back up the vault key in the shared password database:
+   - Create an entry titled "Vault Key" in the collection folder
+   - Store the vault key in this entry
+
 ## 6. Set up collection-specific SSH key
 
-1. Generate a new key:
+1. Generate a new key, which will be used by the Open Terms Archive engine to push changes to the collection on GitHub:
+
    ```shell
-   ssh-keygen --type=ed25519 --comment=[email protected] --passphrase="" --file=./<collection_name>-key
+   ssh-keygen -t ed25519 -C [email protected] -N "" -f ./<collection_name>-key
    ```
 
-2. Encrypt and store the private key:
+2. Encrypt the private key:
+
    ```shell
    # Copy private key to deployment/github-bot-private-key
    ansible-vault encrypt github-bot-private-key
@@ -117,29 +148,40 @@ First, ensure your server provides unsupervised access:
    - Go to github.com/settings/ssh/new
    - Add the public key with title "<collection_name> collection"
 
+4. [🔒 **Specific to Open Terms Archive organization members**] Back up the key in the shared password database:
+   - Create an entry titled "OTA-Bot GitHub SSH key" in the collection folder
+   - Store both public and private keys in this entry
+
 ## 7. Configure email notifications
 
 1. Generate SMTP credentials:
    - Create a new SMTP key in Brevo
    - Name it "<collection_name> collection"
 
 2. Store the credentials:
+
    ```shell
    # In deployment/.env:
    OTA_ENGINE_SMTP_PASSWORD=your_smtp_key
    ```
 
 3. Encrypt the `.env` file:
+
    ```shell
    ansible-vault encrypt .env
    ```
 
+4. [🔒 **Specific to Open Terms Archive organization members**] Back up the credentials in the shared password database:
+   - Create an entry titled "SMTP Key" in the collection folder
+   - Store the credentials in this entry
+
 ## 8. Test the deployment
 
 1. Via GitHub Actions:
    - Check that the `deploy` action completes successfully
 
 2. Via local deployment:
+
    ```shell
    cd <collection_id>-declarations/deployment
    ansible-galaxy collection install --requirements-file requirements.yml