Add INSTALL.md with Debian/Ubuntu setup instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 103 insertions, 0 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..2a8df29
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,103 @@
+# 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
+```