Day 2 Operations

Day 2 Operations

Common tasks you'll need to do after the initial setup. This is the "how do I..." page.

Adding a New Disk

1. Physically install the disk in the NAS
2. Format and label the disk:

   sudo mkfs.ext4 -L ARRAY-DISK5 /dev/sdX

3. Update group_vars — add the new disk to storage_disks:

   storage_disks:
     - { label: "ARRAY-DISK1", mount: "/mnt/disk1" }
     - { label: "ARRAY-DISK2", mount: "/mnt/disk2" }
     - { label: "ARRAY-DISK3", mount: "/mnt/disk3" }
     - { label: "ARRAY-DISK4", mount: "/mnt/disk4" }
     - { label: "ARRAY-DISK5", mount: "/mnt/disk5" }  # ← new

4. Update the MergerFS source (if applicable) to include the new mount
5. Push to main — the provisioning pipeline will mount the disk and add it to the pool

Adding a New Secret

1. Add the secret to Azure KeyVault:

   az keyvault secret set --vault-name <name> --name "my-new-secret" --value "the-value"

2. Reference it in the appropriate config file using the token pattern:

   my_config_value: "#{MY_NEW_SECRET}#"

   (Remember: my-new-secret in KeyVault becomes MY_NEW_SECRET as an env var)
3. Commit and push — the workflow dynamically pulls all secrets, no workflow changes needed

Adding a New User

1. Add to the users list in group_vars:

   users:
     - name: newuser
       comment: "Description"
       groups: [docker]
       ssh_key: #{SSH_PUBKEY_NEWUSER}

   💡 The SSH public key should be stored as a secret in Azure KeyVault (e.g. ssh-pubkey-newuser) so it's injected via token replacement — never hardcode keys in group_vars.

2. If the user needs directory access, update host_directories with appropriate ACLs

3. Push to main

Adding a New Role

1. Create the role directory structure under playbooks/roles/owendemooy.newrole/
2. Add the role name to the functions list in group_vars
3. Add the conditional include in provision.yml:

   - name: New Role
     ansible.builtin.include_role:
       name: owendemooy.newrole
     when: "'newrole' in functions"

4. Push to main

Rebuilding the NAS

If the NAS hardware dies or you're migrating to new hardware:

1. Move Disks to the new server (the Array and Parity Disks)
2. Install Ubuntu Server on the new hardware (minimal install)
3. Set the IP to match what's in the inventory (e.g. 10.1.1.118)
4. Add your SSH public key to the user's authorized_keys
5. Update GitHub Secrets if needed:
   • HOST_FINGERPRINT — the new machine will have new SSH host keys
   • WG_CONFIG_FILE — only if the WireGuard peer config changes
6. Run the provisioning pipeline — it will configure everything from scratch
7. Restore from backup — run restore.sh to bring back Docker persistent data
8. Run the container deployment — deploys all Docker stacks

💡 Steps 5-7 get you from bare metal to fully running in minutes (plus backup restore time). That's the whole point of this project.

Troubleshooting a Failed Run

1. Check the GitHub Actions job summary — it shows a structured recap
2. Look at the specific failed step in the workflow log
3. Common issues:
   • WireGuard timeout — is the home WG endpoint reachable? Check ISP/router
   • SSH refused — did the NAS host keys change? Update HOST_FINGERPRINT
   • Ansible task failed — read the error message, it's usually clear
   • KeyVault access denied — SPN credentials may have expired (they have a default 1-year lifetime)