# 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.

## 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
```