🖥️ Host Administration Runbooks

Audience: System Administrators / DevOps Leads Purpose: Standard Operating Procedures (SOPs) for managing users, permissions, and core packages on the bare-metal Debian host.

Root Access Warning

Avoid executing commands as the root user directly. Always log in with your personal admin account and use sudo.

1. Create a New Developer Account

We grant developers server access without giving them full root privileges. Developers are permitted to log in and switch to the app-runner service account to perform deployments.

Step 1: Create the System User

sudo adduser <username>

Set a secure temporary password and store it in the company password manager to share with the new hire.

Step 2: Grant Deployment Permissions (Limited Sudo)

We do not add developers to the sudo group. We allow them to switch only to the app-runner user.

Open the sudo configuration safely:
```
sudo visudo
```

Scroll to the bottom and append this rule (replace <username>):

# Allow <username> to switch to app-runner without a password
<username> ALL=(app-runner) NOPASSWD: ALL

Step 3: Inject SSH Key

Do not rely on the temporary password. Once the user provides their ed25519.pub key:

sudo su - <username>
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/authorized_keys # Paste the public key here
chmod 600 ~/.ssh/authorized_keys
exit

2. The `app-runner` Context Switch

When an engineer needs to restart a container or pull code, they must switch to the service account. Never run docker compose up as your personal user.

# Switch from personal user to the service account
sudo -u app-runner -H bash

Verify the prompt changes to app-runner@server: before touching the /opt/ directories.

Appendix: Bare-Metal Docker Installation

If the server is ever rebuilt, do not use apt install docker.io. We require the official Docker repository to support modern Compose V2 features.

1. Clean the System:

sudo apt-get remove docker docker-engine docker.io containerd runc

2. Add the Official GPG Key:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL [https://download.docker.com/linux/debian/gpg](https://download.docker.com/linux/debian/gpg) | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. Setup the Repository & Install:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] [https://download.docker.com/linux/debian](https://download.docker.com/linux/debian) $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

4. Permission Configuration:

sudo groupadd docker
sudo usermod -aG docker app-runner