Improve how to deploy a collection

content/deployment/how-to/deploy.md

@@ -25,7 +25,13 @@ First, ensure your server provides unsupervised access:
 1. Check the SSH host key and get the SSH fingerprint by running the following command on your local machine:
 
    ```shell
-   ssh-keyscan -t ed25519 <server_address>
+   ssh-keyscan -t ed25519 <server_address> | grep -v '^#' | cut -d' ' -f3
+   ```
+
+   You should get an output that should be saved for later use as `<server_ssh_fingerprint>`. It will look like this:
+
+   ```shell
+   AAAAC3NzaC1lZDI1NTE5AAAAIGvJ9Al5cU7WwQ9a2m5oRmd3XjTzGQ1nBNiYFLm0TtB5
    ```
 
    If no Ed25519 key appears, generate one by running the following commands on the server:
@@ -37,16 +43,26 @@ First, ensure your server provides unsupervised access:
 
    > **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:
+2. Connect to the server and create a dedicated user account specifically for deployment purposes, by running the following commands:
 
    ```shell
-   adduser <deployment_user>
+   adduser --disabled-password  <deployment_user>
    usermod --append --groups=sudo <deployment_user>
    ```
 
+   > **Note**: The `--disabled-password` option creates a user account that cannot log in with a password unless one is explicitly set later. This is a security measure since the deployment process will use SSH keys for authentication instead of passwords.
+
    > **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 passwordless sudo access for this user, by adding the following line to the `/etc/sudoers` file on the server:
+3. Create and configure the SSH directory for the deployment user by running these commands on the server:
+
+   ```shell
+   sudo mkdir /home/<deployment_user>/.ssh
+   sudo chmod 700 /home/<deployment_user>/.ssh
+   sudo chown <deployment_user>:<deployment_user> /home/<deployment_user>/.ssh
+   ```
+
+4. Configure passwordless sudo access for this deployment user, by adding the following line to the `/etc/sudoers` file on the server:
 
    ```shell
    <deployment_user> ALL=(ALL) NOPASSWD:ALL
@@ -73,20 +89,20 @@ First, ensure your server provides unsupervised access:
    ```
 
 3. Add the server fingerprint to GitHub, to allow the deployment workflow to uniquely identify the server:
-   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions`
+   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions/new`
    - Create a new secret named `SERVER_FINGERPRINT` with your Ed25519 fingerprint
 
 ## 3. Configure SSH deployment keys
 
 1. On the server, generate a deployment key, which will be used by the continuous deployment workflow to connect to the server to deploy the collection:
 
    ```shell
-   ssh-keygen -t ed25519 -N "" -f ~/.ssh/ota-deploy
-   cat ~/.ssh/ota-deploy.pub >> ~/.ssh/authorized_keys
+   ssh-keygen -t ed25519 -N "" -f /home/<deployment_user>/.ssh/ota-deploy
+   cat /home/<deployment_user>/.ssh/ota-deploy.pub >> /home/<deployment_user>/.ssh/authorized_keys
    ```
 
 2. Add the private key to GitHub, to allow the deployment workflow to connect to the server:
-   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions`
+   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions/new`
    - Create a new secret named `SERVER_SSH_KEY` with the private key content
 
 {{< showIfParam "ota" >}}
@@ -98,13 +114,17 @@ First, ensure your server provides unsupervised access:
 1. Log in as the user account dedicated to bot-related actions in GitHub
 
 2. Create a fine-grained GitHub token:
-   - Create a new token at github.com/settings/personal-access-tokens/new
-   - Set repository access for both declarations and versions repositories
-   - Grant "Contents" and "Issues" write permissions
+   - Go to [https://github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
+   - Select an option for the "Resource owner", it can be the organization or the user account
+   - Set the expiration date to "No expiration"
+   - If the resource owner is an organization, in "Repository access", select "Only select repositories" and select the `<collection_id>-declarations` and `<collection_id>-versions` repositories
+   - If the resource owner is a user account, in "Repository access", select "All repositories"
+   - In "Permissions", select "Repository permissions" and grant "Contents" and "Issues" "Read and write" permissions
+   - Click on "Generate token"
 
-3. If relevant, get the token approved by having an organization admin approve the token request
+3. If the resource owner is an organization, have an organization admin approve the token request. This step is not needed if the resource owner is a user account.
 
-4. Keep this token for the next steps
+4. Keep this token for later use as `<github_token>`
 
 {{< showIfParam "ota" >}}
 5. Back up the token in the shared password database by creating an entry titled "GitHub Token" in the collection folder and storing the token in this entry
@@ -127,7 +147,7 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
 2. Store the GitHub token, generated in the previous section, in `deployment/.env`:
 
    ```shell
-   OTA_ENGINE_GITHUB_TOKEN=your_token
+   OTA_ENGINE_GITHUB_TOKEN=<github_token>
    ```
 
 3. Encrypt the `.env` file by running the following command inside the `deployment` folder of the collection:
@@ -158,13 +178,24 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
 
 ## 6. Set up collection-specific SSH key
 
-1. Generate a new key, which will be used by the Open Terms Archive engine to perform actions on GitHub as the bot user:
+1. On your local machine, generate a new key, which will be used by the Open Terms Archive engine to perform actions on GitHub as the bot user:
 
    ```shell
    ssh-keygen -t ed25519 -C [email protected] -N "" -f ./<collection_name>-key
    ```
 
-2. Store the private key in `deployment/github-bot-private-key`
+2. Store the private key by replacing the whole content of `deployment/github-bot-private-key` with the content of the private key file you just generated (`./<collection_name>-key`). Make sure to include the entire key, including the "-----BEGIN OPENSSH PRIVATE KEY-----" and "-----END OPENSSH PRIVATE KEY-----" lines, with the newline at the end of the file. It should look like this:
+
+   ```shell
+   -----BEGIN OPENSSH PRIVATE KEY-----
+   b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAlwAAAAdzc2gt
+   ZWQyNTUxOQAAACDXr7PSaRM0YeIrCZ3NEyyMy7nzzvTWQ78EoUmsRt6W0wAAAJiKDTHV
+   ig0x1QAAAAdzc2gtZWQyNTUxOQAAACDXr7PSaRM0YeIrCZ3NEyyMy7nzzvTWQ78EoUms
+   Rt6W0wAAAECrEN7xyX4h8r5wP0Adtz3WqIS8Su8D6UnyCm9tZyNNdavi89JpEzRh4isJ
+   nc0TLIzLufPO9NZDvwShSayG3pbTAAAAE2Zha2VAdGVzdC5sb2NhbAECAwQFBgc=
+   -----END OPENSSH PRIVATE KEY-----
+
+   ```
 
 3. Encrypt the private key file by running the following command inside the `deployment` folder of the collection:
 
@@ -175,7 +206,8 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
 4. Commit the changes to the repository
 
 5. Add the public key to bot user's GitHub account:
-   - Go to github.com/settings/ssh/new
+   - Still logged in as the user account dedicated to bot-related actions in GitHub
+   - Go to [https://github.com/settings/ssh/new](https://github.com/settings/ssh/new)
    - Add the public key with title "<collection_name> collection"
 
 {{< showIfParam "ota" >}}
@@ -231,4 +263,8 @@ This section describes how to configure the engine to use a specific SMTP server
    ansible-playbook opentermsarchive.deployment.deploy
    ```
 
+   > **Note**: The local deployment will only work if your personal SSH key is authorized to connect to the deployment user on the server. If you haven't done this yet, follow these steps:
+   > 1. On your local machine, copy your public SSH key
+   > 2. Connect to the server and paste the key at the end of the `/home/<deployment_user>/.ssh/authorized_keys` file
+
 If all steps complete successfully, your collection should now be properly deployed and running.