mirror of
https://github.com/seanmorley15/AdventureLog.git
synced 2026-07-30 23:38:02 -04:00
ab698ee8ba
- Introduced a new `source` field in the `ContentImage` model to track the origin of images (e.g., upload, Google, Wikipedia, URL, Immich). - Added a `source_url` field to store the URL associated with the image source. - Implemented a `coordinates` field to store GPS data for images. - Enhanced the `ContentImageSerializer` to include the new fields and updated the representation logic. - Created a management command to backfill GPS coordinates for existing images based on EXIF data or Immich metadata. - Added utility functions for resolving image metadata and creating `ContentImage` instances with proper source and coordinates. - Updated various views and services to utilize the new image source and coordinates features. - Added tests to ensure the correct functionality of the new features and metadata handling.
129 lines
3.9 KiB
Markdown
129 lines
3.9 KiB
Markdown
# Operations & Maintenance
|
|
|
|
Day-to-day tasks for a self-hosted AdventureLog instance: updates, backups, validation, and the installer management menu.
|
|
|
|
## Management menu
|
|
|
|
If you installed via the [Quick Start Installer](../install/quick_start.md), re-run it to open the interactive management menu:
|
|
|
|
```bash
|
|
curl -sSL https://get.adventurelog.app | bash
|
|
```
|
|
|
|
Or from your install directory:
|
|
|
|
```bash
|
|
bash install_adventurelog.sh --manage
|
|
```
|
|
|
|
Available actions:
|
|
|
|
| Action | What it does |
|
|
| ------ | ------------ |
|
|
| **Status** | Shows container health and `/health` endpoint |
|
|
| **Update** | Pulls latest images and redeploys (optional backup first) |
|
|
| **Reconfigure** | Re-runs the configuration wizard |
|
|
| **Backup** | Runs `scripts/backup.sh` |
|
|
| **Restore** | Runs `scripts/restore.sh` from a backup folder |
|
|
| **Logs** | Follows container logs |
|
|
| **Restart** | Restarts the compose stack |
|
|
| **Uninstall** | Stops containers, removes volumes |
|
|
|
|
## Compose file detection
|
|
|
|
`scripts/deploy.sh`, `scripts/backup.sh`, and `scripts/restore.sh` auto-detect your setup:
|
|
|
|
| Condition | Compose file | Env file |
|
|
| --------- | ------------ | -------- |
|
|
| Only `.env` exists | `docker/docker-compose.yml` | `.env` |
|
|
| Only `.env.advanced` exists | `docker/docker-compose.advanced.yml` | `.env.advanced` |
|
|
| `ADVENTURELOG_COMPOSE=advanced` with both env files | `docker/docker-compose.advanced.yml` | `.env.advanced` |
|
|
| Otherwise | `docker/docker-compose.yml` | `.env` |
|
|
|
|
Override manually:
|
|
|
|
```bash
|
|
COMPOSE_FILE=docker/docker-compose.advanced.yml bash scripts/deploy.sh --backup
|
|
```
|
|
|
|
Always pass `--env-file` when running `docker compose` directly:
|
|
|
|
```bash
|
|
docker compose --env-file .env -f docker/docker-compose.yml ps
|
|
```
|
|
|
|
## Updating
|
|
|
|
See [Updating](updating.md) for full details. Quick reference:
|
|
|
|
```bash
|
|
# Recommended — validates env, backs up, pulls, and waits for health
|
|
bash scripts/deploy.sh --backup
|
|
|
|
# Advanced Deployment with explicit compose file
|
|
COMPOSE_FILE=docker/docker-compose.advanced.yml bash scripts/deploy.sh --backup
|
|
```
|
|
|
|
## Backup
|
|
|
|
`scripts/backup.sh` creates a timestamped folder under `backups/` containing:
|
|
|
|
- Your env file (`.env` or `.env.advanced`)
|
|
- PostgreSQL dump (`database.sql`)
|
|
- Media volume archive (`media.tar.gz`)
|
|
|
|
```bash
|
|
bash scripts/backup.sh
|
|
# Custom output directory:
|
|
BACKUP_DIR=/mnt/backups bash scripts/backup.sh
|
|
```
|
|
|
|
## Restore
|
|
|
|
```bash
|
|
bash scripts/restore.sh backups/20260101-120000
|
|
```
|
|
|
|
This stops the stack, restores env + database + media, and brings containers back up.
|
|
|
|
## Environment validation
|
|
|
|
Run before every deploy or after editing env files:
|
|
|
|
```bash
|
|
bash scripts/validate-env.sh
|
|
bash scripts/validate-env.sh .env
|
|
bash scripts/validate-env.sh .env.advanced
|
|
```
|
|
|
|
The validator catches common mistakes such as `PUBLIC_SERVER_URL` pointing at the host backend port instead of the internal Docker service name.
|
|
|
|
## Image GPS backfill
|
|
|
|
New uploads and imports store GPS coordinates on `ContentImage` records when EXIF or Immich metadata is available. Images imported before this feature, or stored as WEBP without retained EXIF, may not have coordinates until you backfill them.
|
|
|
|
Run inside the backend container:
|
|
|
|
```bash
|
|
docker compose exec server python3 manage.py backfill_image_coordinates
|
|
```
|
|
|
|
Useful options:
|
|
|
|
| Flag | Purpose |
|
|
| ---- | ------- |
|
|
| `--dry-run` | Show what would be updated without saving |
|
|
| `--user-id ID` | Limit to one user's images |
|
|
| `--batch-size N` | Progress logging interval (default 100) |
|
|
| `--force` | Re-extract even when coordinates already exist |
|
|
| `--verbose` | Log each processed image |
|
|
|
|
The command tries, in order:
|
|
|
|
1. **Local file** — reads the stored image and extracts EXIF GPS (may fail for WEBP conversions that stripped metadata)
|
|
2. **Immich reference** — fetches GPS from the linked Immich asset when `immich_id` is set and the user has an Immich integration
|
|
|
|
After backfill, geotagged images appear on maps when **Photo locations** is enabled in the map display options.
|
|
|
|
## First boot behavior
|