# Installing Albumen

Tested on Debian 12 and Ubuntu 22.04/24.04.

## System packages

```bash
apt install -y \
  ruby ruby-dev ruby-bundler \
  build-essential \
  imagemagick \
  libimage-exiftool-perl \
  ffmpeg \
  nginx
```

| Package | Purpose |
|---|---|
| `ruby`, `ruby-dev`, `ruby-bundler` | Runtime and gem builds |
| `build-essential` | Compiling native gems (bcrypt) |
| `imagemagick` | Thumbnail generation for images |
| `libimage-exiftool-perl` | EXIF date/metadata extraction (`exiftool` command) |
| `ffmpeg` | Thumbnail generation and duration extraction for videos |
| `nginx` | Reverse proxy in front of Puma |

## Deploy the app

Copy the app files to `/opt/albumen` (adjust source path as needed):

```bash
rsync -a /path/to/albumen/ /opt/albumen/
```

## Run the setup script

Run once as root. Creates the `albumen` service user, installs gems, writes the
nginx site config, and installs the systemd unit:

```bash
cd /opt/albumen
bash setup.sh
```

## Set the admin password

```bash
ruby /opt/albumen/scripts/set_password.rb
```

This writes a bcrypt hash to `/opt/albumen/config.yml` and generates a random
session secret if one is not already present.

## Start the service

```bash
systemctl start albumen
systemctl status albumen      # confirm it's running
journalctl -u albumen -f      # tail the logs
```

## Add photos

Drop albums (directories of image/video files) into `/var/albumen/`, then run
the update script to generate thumbnails and extract EXIF metadata:

```bash
ruby /opt/albumen/scripts/update.rb
```

Pass a subdirectory name to process only that album:

```bash
ruby /opt/albumen/scripts/update.rb 2024_Hawaii
```

The script is safe to re-run; already-done work is skipped.

## Choosing HTTP (port 80) vs HTTPS (port 443)

### Port 80 — HTTP

The nginx config installed by `setup.sh` listens on port 80 and is ready to use
as-is. HTTP is fine when:

- The server is only reachable on a private/home network, **and**
- You're not worried about traffic being intercepted on that network

It is **not** appropriate for a server reachable from the public internet —
passwords and session cookies travel in the clear.

### Port 443 — HTTPS with Let's Encrypt

HTTPS encrypts all traffic between the browser and the server. It requires a
real domain name (not a bare IP address) that points to the server.
[Let's Encrypt](https://letsencrypt.org/) provides free, automatically-renewed
TLS certificates via the **Certbot** tool.

**1. Install Certbot:**

```bash
apt install -y certbot python3-certbot-nginx
```

**2. Obtain a certificate and auto-configure nginx:**

```bash
certbot --nginx -d yourdomain.example.com
```

Certbot will:
- Prove ownership of the domain (Let's Encrypt contacts your server on port 80)
- Write a certificate to `/etc/letsencrypt/live/yourdomain.example.com/`
- Edit `/etc/nginx/sites-enabled/albumen` to add a port-443 listener, point it
  at the certificate files, and add an HTTP→HTTPS redirect on port 80
- Reload nginx automatically

**3. Verify auto-renewal:**

Certbot installs a systemd timer that renews certificates before they expire
(they last 90 days). Confirm it's active:

```bash
systemctl status certbot.timer
```

You can also do a dry-run to make sure renewal would succeed:

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

That's it — no further configuration is needed. Certbot manages everything
from here.

**Firewall note:** If the server has a firewall, make sure ports 80 and 443 are
both open. Port 80 must remain open even after switching to HTTPS because
Let's Encrypt uses it for renewal challenges.

```bash
ufw allow 'Nginx Full'   # if using ufw
```

---

## nginx: real client IPs (optional)

If Albumen sits behind an upstream proxy that adds `X-Forwarded-For`, tell
nginx to use it as the real client address. Add these two lines inside the
`server {}` block in `/etc/nginx/sites-enabled/albumen`, replacing the IP with
your proxy's address:

```nginx
real_ip_header   X-Forwarded-For;
set_real_ip_from 192.168.1.1;
```

Then reload nginx:

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

## Directory layout

```
/opt/albumen/          app code, gems, config, logs
/opt/albumen/config.yml       admin password hash + session secret (mode 600)
/opt/albumen/cache/thumbs/    generated thumbnails (safe to delete and regenerate)
/var/albumen/          media root — albums live here
```