# Lightbox

Lightbox is a self-hosted photo library for importing, organizing, searching, and sharing personal photo collections. It runs on your own server, stores originals on disk, and keeps metadata in a database you control.

## Features

- Automatic photo and video import from watched folders
- Timeline view grouped by year, month, and day
- Albums, favorites, tags, and basic people labels
- Full-text search across filenames, locations, tags, and EXIF metadata
- Thumbnail and preview generation
- Duplicate detection using file hashes
- Private sharing links with optional expiry dates
- Multi-user accounts with read-only or editor roles
- Background jobs for imports, indexing, and cleanup
- Docker-based deployment

## Install

### Requirements

- Docker 24+
- Docker Compose v2+
- 2 GB RAM minimum
- Persistent storage for originals, thumbnails, and database files

### Docker Compose

Create a `docker-compose.yml` file:

```yaml
services:
  lightbox:
    image: ghcr.io/example/lightbox:latest
    container_name: lightbox
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      LIGHTBOX_BASE_URL: http://localhost:8080
      LIGHTBOX_DATABASE_URL: postgres://lightbox:lightbox@postgres:5432/lightbox
      LIGHTBOX_LIBRARY_PATH: /library
      LIGHTBOX_UPLOAD_PATH: /uploads
      LIGHTBOX_THUMBNAIL_PATH: /cache/thumbnails
      LIGHTBOX_SECRET_KEY: change-this-to-a-long-random-value
    volumes:
      - ./library:/library
      - ./uploads:/uploads
      - ./cache:/cache
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    container_name: lightbox-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: lightbox
      POSTGRES_USER: lightbox
      POSTGRES_PASSWORD: lightbox
    volumes:
      - ./postgres:/var/lib/postgresql/data
```

Start the application:

```sh
docker compose up -d
```

Open `http://localhost:8080` and create the first admin account.

## Usage

### Import Photos

Place photos in the mounted library folder:

```sh
cp -R ~/Pictures/2025 ./library/
```

Then start an import from the web UI, or run:

```sh
docker compose exec lightbox lightbox import /library
```

Lightbox keeps the original files in place and stores generated thumbnails separately.

### Upload From Browser

Use the Upload page to add photos directly from your browser. Uploaded files are written to `LIGHTBOX_UPLOAD_PATH` and indexed automatically.

### Create Albums

Select one or more photos, choose **Add to Album**, then create a new album or add them to an existing one.

### Share Photos

Open an album or selection, choose **Share**, and generate a private link. Shared links can be revoked at any time.

### Backups

Back up the following directories:

```text
./library
./uploads
./cache
./postgres
```

The `library`, `uploads`, and `postgres` directories are required for a complete restore. The `cache` directory can be regenerated, but backing it up speeds up recovery.

## Configuration

Lightbox is configured with environment variables.

| Variable | Default | Description |
| --- | --- | --- |
| `LIGHTBOX_BASE_URL` | `http://localhost:8080` | Public URL used for links and redirects. |
| `LIGHTBOX_DATABASE_URL` | Required | PostgreSQL connection string. |
| `LIGHTBOX_LIBRARY_PATH` | `/library` | Folder scanned for existing photos and videos. |
| `LIGHTBOX_UPLOAD_PATH` | `/uploads` | Folder used for browser uploads. |
| `LIGHTBOX_THUMBNAIL_PATH` | `/cache/thumbnails` | Folder used for generated thumbnails and previews. |
| `LIGHTBOX_SECRET_KEY` | Required | Secret used for sessions and signed share links. |
| `LIGHTBOX_MAX_UPLOAD_MB` | `1024` | Maximum upload size in megabytes. |
| `LIGHTBOX_IMPORT_INTERVAL` | `0` | Automatic scan interval in minutes. Set to `0` to disable. |
| `LIGHTBOX_ALLOW_SIGNUPS` | `false` | Allows public account registration when set to `true`. |
| `LIGHTBOX_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, or `error`. |

Example `.env` file:

```env
LIGHTBOX_BASE_URL=https://photos.example.com
LIGHTBOX_DATABASE_URL=postgres://lightbox:lightbox@postgres:5432/lightbox
LIGHTBOX_LIBRARY_PATH=/library
LIGHTBOX_UPLOAD_PATH=/uploads
LIGHTBOX_THUMBNAIL_PATH=/cache/thumbnails
LIGHTBOX_SECRET_KEY=replace-with-a-long-random-secret
LIGHTBOX_MAX_UPLOAD_MB=2048
LIGHTBOX_IMPORT_INTERVAL=60
LIGHTBOX_ALLOW_SIGNUPS=false
LIGHTBOX_LOG_LEVEL=info
```

After changing configuration, restart the service:

```sh
docker compose restart lightbox
```