# PassKeeper — Deployment Guide

Complete step-by-step instructions for deploying PassKeeper on a fresh Ubuntu server
from zero to a fully running production environment.

**Stack:** Ubuntu 22.04 LTS · Python 3.12 · MySQL 8 · Redis · Gunicorn · Nginx · Certbot (Let's Encrypt)

**Deployment paths used throughout this guide:**

- App directory: `/home/spuser/PassKeeper`
- Virtual env: `/home/spuser/.venv`
- Logs: `/home/spuser/logs/`
- Backups: `/home/spuser/backups/passkeeper/`
- System user: `spuser` (runs the app process)
- Domain: `pwkeeper.ngodanguyen.tech`

> Replace all occurrences of `pwkeeper.ngodanguyen.tech`, `spuser`, and passwords with
> your own values before running any command.

---

## Prerequisites

- A VPS or dedicated server running **Ubuntu 22.04 LTS**
- A registered domain name with an **A record** pointing to your server's public IP
- SSH access as a user with `sudo` privileges
- The PassKeeper source code (this repository) available on the server

---

## Step 1 — System packages

```bash
sudo apt update && sudo apt upgrade -y

sudo apt install -y \
    python3.12 \
    python3.12-venv \
    python3-pip \
    mysql-server \
    redis-server \
    nginx \
    certbot \
    python3-certbot-nginx \
    git \
    curl \
    ufw
```

Verify Python version:

```bash
python3.12 --version   # must be 3.12.x
```

---

## Step 2 — Firewall

Allow only SSH, HTTP, and HTTPS. Everything else is dropped.

```bash
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status
```

---

## Step 3 — MySQL setup

### 3a. Secure the MySQL installation

```bash
sudo mysql_secure_installation
```

Follow the prompts: set a root password, remove anonymous users, disallow remote root
login, remove the test database.

### 3b. Create the database and application user

```bash
sudo mysql -u root -p
```

Inside the MySQL shell:

```sql
CREATE DATABASE passkeeper CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

CREATE USER 'spuser'@'127.0.0.1' IDENTIFIED BY 'your-strong-db-password-here';
GRANT ALL PRIVILEGES ON passkeeper.* TO 'spuser'@'127.0.0.1';
FLUSH PRIVILEGES;
EXIT;
```

> Use a strong, unique password. Update `MYSQL_PASSWORD` in `.env` (Step 6) to match.

Verify the connection:

```bash
mysql -u spuser -p -h 127.0.0.1 passkeeper -e "SELECT 1;"
```

---

## Step 4 — Redis setup

Redis is required for shared rate limiting across all Gunicorn workers.

```bash
sudo systemctl enable redis-server
sudo systemctl start redis-server
redis-cli ping   # should return PONG
```

Redis listens on `127.0.0.1:6379` by default. No password is required for local-only use.
If you want a Redis password, set it in `/etc/redis/redis.conf` and update
`RATELIMIT_STORAGE_URI` in `.env` accordingly.

---

## Step 5 — Deploy the application code

### 5a. Clone or upload the repository

```bash
cd /home/spuser
git clone https://github.com/your-org/passkeeper.git PassKeeper
# — or — upload via scp/rsync:
# scp -r ./PassKeeper spuser@your-server:/home/spuser/PassKeeper
```

### 5b. Create directory structure

```bash
mkdir -p /home/spuser/logs
mkdir -p /home/spuser/backups/passkeeper
chmod 700 /home/spuser/backups/passkeeper
```

### 5c. Create the Python virtual environment

```bash
cd /home/spuser
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r PassKeeper/requirements.txt
```

Verify key packages installed:

```bash
pip show flask gunicorn cryptography redis pyotp
```

---

## Step 6 — Configure environment variables

```bash
cd /home/spuser/PassKeeper
cp .env.example .env    # if an example file exists
# — or — create from scratch:
nano .env
```

Paste the following, replacing every placeholder value:

```ini
FLASK_ENV=production
SECRET_KEY=<generate: python3 -c "import secrets; print(secrets.token_hex(32))">
JWT_SECRET_KEY=<generate: python3 -c "import secrets; print(secrets.token_hex(32))">

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=spuser
MYSQL_PASSWORD=your-strong-db-password-here
MYSQL_DB=passkeeper

ARGON2_TIME_COST=3
ARGON2_MEMORY_COST=65536
ARGON2_PARALLELISM=4

# AES-256-GCM key for encrypting TOTP secrets at rest (REQUIRED)
# Generate: python3 -c "import secrets; print(secrets.token_hex(32))"
TOTP_ENCRYPTION_KEY=<generate as above — 64 hex characters>

# Redis for shared rate limiting across Gunicorn workers
RATELIMIT_STORAGE_URI=redis://127.0.0.1:6379/0

# Lock CORS to your production domain
CORS_ORIGINS=https://pwkeeper.ngodanguyen.tech

# Backup settings
BACKUP_DIR=/home/spuser/backups/passkeeper
BACKUP_RETENTION_DAYS=30
```

Secure the file — it contains secrets:

```bash
chmod 600 /home/spuser/PassKeeper/.env
```

Generate all three keys in one go:

```bash
python3 -c "import secrets; [print(secrets.token_hex(32)) for _ in range(3)]"
```

Use the three output lines for `SECRET_KEY`, `JWT_SECRET_KEY`, and `TOTP_ENCRYPTION_KEY`
respectively.

---

## Step 7 — Initialise the database schema

Activate the virtual environment if not already active:

```bash
source /home/spuser/.venv/bin/activate
cd /home/spuser/PassKeeper
```

### Option A — Fresh install (no existing data)

```bash
python reset_db.py
```

This drops and recreates all tables using `db.create_all()`. Safe only on a fresh
database with no data you care about.

### Option B — Existing database (run all migrations in order)

```bash
export FLASK_APP=wsgi.py
export FLASK_ENV=production
flask db upgrade
```

This runs the three Alembic migrations in sequence:

1. `71d7158dd3b9` — creates `audit_logs`, fixes `sharing_public_key` type
2. `a1b2c3d4e5f6` — widens `totp_secret` to `VARCHAR(255)`, adds `totp_iv`
3. `b2c3d4e5f6a7` — adds `recovery_enc_salt` and `recovery_iv`

### Re-encrypt existing TOTP secrets (only if migrating from an older version)

If you had users with plaintext TOTP secrets before Phase 5, run this one-time script:

```bash
python scripts/reencrypt_totp_secrets.py
```

This is idempotent — it skips users who already have `totp_iv` set and rolls back
atomically on any error.

---

## Step 8 — Test Gunicorn manually

Before installing the systemd service, verify Gunicorn can start the app:

```bash
source /home/spuser/.venv/bin/activate
cd /home/spuser/PassKeeper
gunicorn --workers 4 --bind 127.0.0.1:5000 --preload wsgi:app
```

You should see lines like:

```
[INFO] Listening at: http://127.0.0.1:5000
[INFO] Booting worker with pid: ...
```

Press `Ctrl+C` to stop. If you see errors, check `.env` values and DB connectivity.

---

## Step 9 — systemd service

### 9a. Install the service unit

```bash
sudo cp /home/spuser/PassKeeper/scripts/passkeeper.service \
        /etc/systemd/system/passkeeper.service
```

### 9b. Verify the service file paths match your deployment

```bash
sudo nano /etc/systemd/system/passkeeper.service
```

Confirm these lines are correct for your setup:

```ini
User=spuser
WorkingDirectory=/home/spuser/PassKeeper
EnvironmentFile=/home/spuser/PassKeeper/.env
ExecStart=/home/spuser/.venv/bin/gunicorn ...
--access-logfile /home/spuser/logs/access.log
--error-logfile  /home/spuser/logs/error.log
```

### 9c. Enable and start

```bash
sudo systemctl daemon-reload
sudo systemctl enable passkeeper
sudo systemctl start passkeeper
```

### 9d. Verify it is running

```bash
sudo systemctl status passkeeper
```

You should see `Active: active (running)`. If not:

```bash
journalctl -xeu passkeeper.service --no-pager | tail -50
```

Test that Gunicorn is listening:

```bash
curl -s http://127.0.0.1:5000/ | head -20
```

---

## Step 10 — Nginx configuration

### 10a. Install the site config

```bash
sudo cp /home/spuser/PassKeeper/scripts/passkeeper-nginx.conf \
        /etc/nginx/sites-available/passkeeper
```

### 10b. Update the domain name

```bash
sudo nano /etc/nginx/sites-available/passkeeper
```

Replace `pwkeeper.ngodanguyen.tech` and `passkeeper.ngodanguyen.tech` with your
actual domain(s) in the `server_name` directives.

Also update the static files alias if your deployment path differs:

```nginx
location /static/ {
    alias /home/spuser/PassKeeper/app/static/;
    ...
}
```

### 10c. Enable the site

```bash
sudo ln -s /etc/nginx/sites-available/passkeeper /etc/nginx/sites-enabled/
sudo nginx -t          # must output: configuration file ... syntax is ok
sudo systemctl reload nginx
```

---

## Step 11 — TLS certificate (Let's Encrypt)

Your DNS A record must already be pointing to this server before running Certbot.

```bash
sudo certbot --nginx -d pwkeeper.ngodanguyen.tech
```

Follow the prompts. When Certbot asks about redirects, choose option **2** (redirect
HTTP to HTTPS). Certbot will automatically modify the Nginx config to add the
`ssl_certificate` paths and HTTP → HTTPS redirect block.

Verify auto-renewal works:

```bash
sudo certbot renew --dry-run
```

Confirm the final Nginx config is valid and reload:

```bash
sudo nginx -t && sudo systemctl reload nginx
```

### Test from a browser

Open `https://pwkeeper.ngodanguyen.tech` — you should see the PassKeeper login page
served over HTTPS with a valid certificate.

---

## Step 12 — Log rotation

```bash
sudo cp /home/spuser/PassKeeper/scripts/passkeeper-logrotate \
        /etc/logrotate.d/passkeeper
```

Verify the config is valid:

```bash
sudo logrotate -d /etc/logrotate.d/passkeeper
```

Force an immediate test rotation (creates `.1.gz` files):

```bash
sudo logrotate -f /etc/logrotate.d/passkeeper
ls -lh /home/spuser/logs/
```

---

## Step 13 — Automated database backups

### 13a. Make the backup script executable

```bash
chmod +x /home/spuser/PassKeeper/scripts/backup_db.sh
```

### 13b. Test the backup script manually

```bash
bash /home/spuser/PassKeeper/scripts/backup_db.sh
ls -lh /home/spuser/backups/passkeeper/
```

You should see a `.sql.gz` file. Check the log:

```bash
cat /home/spuser/backups/passkeeper/backup.log
```

### 13c. Schedule via cron

```bash
crontab -e
```

Add the following line (runs daily at 2:00 AM):

```
0 2 * * * /bin/bash /home/spuser/PassKeeper/scripts/backup_db.sh >> /home/spuser/backups/passkeeper/backup.log 2>&1
```

Save and exit. Verify the cron entry was saved:

```bash
crontab -l
```

---

## Step 14 — Final verification checklist

Run through each item to confirm the deployment is healthy:

```bash
# 1. MySQL is running and the DB is accessible
mysql -u spuser -p -h 127.0.0.1 passkeeper -e "SHOW TABLES;"

# 2. Redis is running
redis-cli ping

# 3. Gunicorn service is active
sudo systemctl status passkeeper

# 4. Nginx is active and config is valid
sudo systemctl status nginx
sudo nginx -t

# 5. App responds on localhost
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:5000/

# 6. App responds on HTTPS (replace with your domain)
curl -s -o /dev/null -w "%{http_code}" https://pwkeeper.ngodanguyen.tech/

# 7. Security headers are present
curl -sI https://pwkeeper.ngodanguyen.tech/ | grep -E "Strict-Transport|X-Frame|X-Content|Content-Security"

# 8. Gunicorn logs are being written
tail -20 /home/spuser/logs/access.log
tail -20 /home/spuser/logs/error.log

# 9. No errors in the systemd journal
journalctl -u passkeeper --since "5 minutes ago" --no-pager
```

Expected HTTP status codes: `200` from both `127.0.0.1:5000` and `https://yourdomain`.

---

## Routine Operations

### Deploying a code update

```bash
cd /home/spuser/PassKeeper

# Pull new code
git pull origin main

# Install any new dependencies
source /home/spuser/.venv/bin/activate
pip install -r requirements.txt

# Run any new database migrations
export FLASK_APP=wsgi.py FLASK_ENV=production
flask db upgrade

# Reload Gunicorn zero-downtime (sends USR2 to master)
sudo systemctl reload passkeeper

# Verify
sudo systemctl status passkeeper
```

### Restarting the app (full restart, brief downtime)

```bash
sudo systemctl restart passkeeper
```

### Viewing live logs

```bash
# Gunicorn access log (all HTTP requests)
tail -f /home/spuser/logs/access.log

# Gunicorn error log (Python exceptions, startup errors)
tail -f /home/spuser/logs/error.log

# systemd journal (service lifecycle events)
journalctl -fu passkeeper
```

### Checking rate limit behaviour (Redis)

```bash
redis-cli
> KEYS *
> DBSIZE
```

### Manual database backup

```bash
bash /home/spuser/PassKeeper/scripts/backup_db.sh
```

### Restoring a database backup

```bash
# List available backups
ls -lh /home/spuser/backups/passkeeper/*.sql.gz

# Restore (replace filename with the one you want)
gunzip -c /home/spuser/backups/passkeeper/passkeeper_20260418_020001.sql.gz \
    | mysql -u spuser -p -h 127.0.0.1 passkeeper
```

### Renewing the TLS certificate manually

```bash
sudo certbot renew
sudo systemctl reload nginx
```

Certbot auto-renewal runs twice daily via a systemd timer — manual renewal is usually
only needed for testing.

---

## Troubleshooting

### `502 Bad Gateway` from Nginx

Gunicorn is down or not listening. Check:

```bash
sudo systemctl status passkeeper
journalctl -xeu passkeeper.service --no-pager | tail -30
curl http://127.0.0.1:5000/
```

Common causes: wrong path in `EnvironmentFile`, missing `.env` variable, MySQL not
reachable at startup. Fix the root cause, then:

```bash
sudo systemctl restart passkeeper
```

### `Connection refused` on port 5000

Gunicorn crashed. Check the error log:

```bash
tail -50 /home/spuser/logs/error.log
```

If it's a startup error (e.g. bad `TOTP_ENCRYPTION_KEY` format), fix `.env` and restart.

### `500 Internal Server Error`

Application exception. Check:

```bash
tail -50 /home/spuser/logs/error.log
journalctl -u passkeeper --since "1 minute ago" --no-pager
```

### Database connection errors

```bash
# Test connectivity directly
mysql -u spuser -p -h 127.0.0.1 passkeeper -e "SELECT 1;"

# Check MySQL is running
sudo systemctl status mysql

# Check .env has correct credentials
grep MYSQL /home/spuser/PassKeeper/.env
```

### Certbot / TLS renewal fails

```bash
# Check DNS is resolving to this server
dig +short pwkeeper.ngodanguyen.tech

# Check Nginx serves port 80 (needed for ACME challenge)
sudo nginx -t
sudo systemctl status nginx
```

### Rate limiting too aggressive (429 errors)

Check Redis is running (if Redis is down, Flask-Limiter falls back to in-memory
counters that reset on every request, which may cause unexpected behaviour):

```bash
redis-cli ping
sudo systemctl status redis-server
```

---

## Environment Variable Reference

| Variable                | Required | Description                                                      |
| ----------------------- | -------- | ---------------------------------------------------------------- |
| `FLASK_ENV`             | Yes      | `production` or `development`                                    |
| `SECRET_KEY`            | Yes      | Flask session signing key — 32-byte hex                          |
| `JWT_SECRET_KEY`        | Yes      | JWT signing key — 32-byte hex                                    |
| `MYSQL_HOST`            | Yes      | MySQL host (usually `127.0.0.1`)                                 |
| `MYSQL_PORT`            | Yes      | MySQL port (usually `3306`)                                      |
| `MYSQL_USER`            | Yes      | MySQL username                                                   |
| `MYSQL_PASSWORD`        | Yes      | MySQL password                                                   |
| `MYSQL_DB`              | Yes      | Database name (`passkeeper`)                                     |
| `TOTP_ENCRYPTION_KEY`   | Yes      | 64-char hex — AES-256-GCM key for TOTP secrets                   |
| `RATELIMIT_STORAGE_URI` | Yes      | `redis://127.0.0.1:6379/0` in production                         |
| `CORS_ORIGINS`          | Yes      | Your production domain, e.g. `https://pwkeeper.ngodanguyen.tech` |
| `ARGON2_TIME_COST`      | No       | Default `3`                                                      |
| `ARGON2_MEMORY_COST`    | No       | Default `65536` (64 MB)                                          |
| `ARGON2_PARALLELISM`    | No       | Default `4`                                                      |
| `BACKUP_DIR`            | No       | Default `/home/spuser/backups/passkeeper`                        |
| `BACKUP_RETENTION_DAYS` | No       | Default `30`                                                     |