Creating Albums from Directory Structures in Immich

A comprehensive guide to automated photo album organization. Based on / With use off the script of Solvoxia at GitHub (see below for credits).

Initial Setup

First, create the necessary directory structure and API key configuration:

mkdir -p /mnt/Immich-Library/api_keysCopy

echo "api_key_User-1_from_Immich" > /mnt/Immich-Library/api_keys/User-1.keyCode language: JavaScript (javascript)Copy

echo "api_key_User-2_from_Immich" > /mnt/Immich-Library/api_keys/User-2.keyCode language: JavaScript (javascript)Copy

Testing Outside Immich Docker Environment

Before integrating with the main Immich stack, let’s verify the configuration:

docker run \
  --rm \
  -v /mnt/Immich-Library/api_keys/User-1.key:/config/api_keys/User-1.key:ro \
  -v /mnt/Immich-Library/external/User-1:/photos/User-1:ro \
  -e API_URL=http://192.168.1.8:2283/api \
  -e API_KEY_FILE=/config/api_keys/User-1.key \
  -e ROOT_PATH=/mnt/Immich-Library/external/User-1 \
  -e DRY_RUN=true \
  -e LOG_LEVEL=DEBUG \
  -e TZ=Europe/Amsterdam \
  -e ALBUM_LEVELS=2 \
  --entrypoint "/script/immich_auto_album.sh" \
  salvoxia/immich-folder-album-creator:latestCode language: JavaScript (javascript)Copy

Creating Convenience Functions

Add these functions to your ~/.bashrc for easier testing and management:

nano ~/.bashrcCopy

function test-albums-event() {
    docker run --rm \
    -v "/mnt/Immich-Library/api_keys/$1.key:/config/api_keys/$1.key:ro" \
    -v "/mnt/Immich-Library/external/$1:/photos/$1:ro" \
    -e API_URL=http://192.168.1.8:2283/api \
    -e API_KEY_FILE="/config/api_keys/$1.key" \
    -e ROOT_PATH="/photos/$1" \
    -e ALBUM_SEPARATOR=" - " \
    -e DRY_RUN=true \
    -e LOG_LEVEL=DEBUG \
    -e TZ=Europe/Amsterdam \
    -e ALBUM_LEVELS="2,2" \
    -e IGNORE="????/????-??/**" \
    -e SHARE_WITH="$2" \
    --entrypoint "/script/immich_auto_album.sh" \
    salvoxia/immich-folder-album-creator:latest
}

function test-albums-year() {
    docker run --rm \
    -v "/mnt/Immich-Library/api_keys/$1.key:/config/api_keys/$1.key:ro" \
    -v "/mnt/Immich-Library/external/$1:/photos/$1:ro" \
    -e API_URL=http://192.168.1.8:2283/api \
    -e API_KEY_FILE="/config/api_keys/$1.key" \
    -e ROOT_PATH="/photos/$1" \
    -e ALBUM_SEPARATOR=" - " \
    -e DRY_RUN=true \
    -e LOG_LEVEL=DEBUG \
    -e TZ=Europe/Amsterdam \
    -e ALBUM_LEVELS=1 \
    -e PATH_FILTER="????/????-??/*" \
    -e IGNORE="" \
    -e SHARE_WITH="$2" \
    --entrypoint "/script/immich_auto_album.sh" \
    salvoxia/immich-folder-album-creator:latest
}Code language: JavaScript (javascript)Copy

After adding these functions, reload your bash configuration:

source ~/.bashrcCopy

Now we can test creating albums per user:

generate-albums <user-name>Code language: HTML, XML (xml)Copy

Docker Compose Integration

Here’s the adapted configuration for integrating album creation into your Immich stack. Note: I’ve maintained the essential infrastructure while anonymizing user-specific details.
CAUTION: please add the extra space [ ] at the end of the CRON line, otherwise the script doesn’t work….. took me a while

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
      - /mnt/Immich-Library/internal:/mnt/Immich-Library/internal:rw
      - /mnt/Immich-Library/external/User-1:/photos/User-1:rw
      - /mnt/Immich-Library/external/User-2:/photos/User-2:rw
    env_file:
      - .env
    ports:
      - '2283:2283'
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  # Event-based Album Creator for User-1
  immich-folder-album-creator-user1-EVENT:
    container_name: immich_folder_album_creator_user1_EVENT
    image: salvoxia/immich-folder-album-creator:latest
    restart: unless-stopped
    volumes:
      - /mnt/Immich-Library/api_keys/User-1.key:/config/api_keys/User-1.key:ro
      - /mnt/Immich-Library/external/User-1:/photos/User-1:ro
    environment:
      API_URL: http://192.168.1.8:2283/api
      API_KEY_FILE: /config/api_keys/User-1.key
      ROOT_PATH: /photos/User-1
      LOG_LEVEL: DEBUG
      # Choose your preferred schedule:
      #CRON_EXPRESSION: "0 19 * * * "    # Daily at 19:00
      CRON_EXPRESSION: "*/5 * * * * "    # Every 5 minutes (for testing)
      TZ: Europe/Amsterdam
      ALBUM_LEVELS: "2,2"
      IGNORE: "????/????-??/**"
      ALBUM_SEPARATOR: " - "

  # Year-based Album Creator for User-1
  immich-folder-album-creator-user1-YEAR:
    container_name: immich_folder_album_creator_user1_YEAR
    image: salvoxia/immich-folder-album-creator:latest
    restart: unless-stopped
    volumes:
      - /mnt/Immich-Library/api_keys/User-1.key:/config/api_keys/User-1.key:ro
      - /mnt/Immich-Library/external/User-1:/photos/User-1:ro
    environment:
      API_URL: http://192.168.1.8:2283/api
      API_KEY_FILE: /config/api_keys/User-1.key
      ROOT_PATH: /photos/User-1
      LOG_LEVEL: DEBUG
      CRON_EXPRESSION: "*/5 * * * * "
      TZ: Europe/Amsterdam
      ALBUM_LEVELS: 1
      PATH_FILTER: "????/????-??/*"
      ALBUM_SEPARATOR: " - "Code language: PHP (php)Copy

Album Management Tools

Album Deletion

Sometimes you need to start fresh. Here’s a powerful tool for removing all albums. Use with caution – this operation cannot be undone!

function delete-albums() {
    local user_name=$1
    docker run --rm \
    -v "/mnt/Immich-Library/api_keys/${user_name}.key:/config/api_keys/${user_name}.key:ro" \
    -v "/mnt/Immich-Library/external/${user_name}:/photos/${user_name}:ro" \
    -e API_URL="http://192.168.1.8:2283/api" \
    -e API_KEY_FILE="/config/api_keys/${user_name}.key" \
    -e ROOT_PATH="/photos/${user_name}" \
    -e MODE="DELETE_ALL" \
    -e DELETE_CONFIRM="true" \
    -e LOG_LEVEL="DEBUG" \
    -e TZ="Europe/Amsterdam" \
    -e ALBUM_LEVELS="3" \
    salvoxia/immich-folder-album-creator:latest \
    /script/immich_auto_album.sh
}Code language: JavaScript (javascript)Copy

Pro Tips

1. Always test first: Use the dry-run mode before making any changes to your album structure
2. Backup your configuration: Keep copies of your API keys and docker-compose files
3. Monitor logs: The DEBUG log level helps troubleshoot any issues that might arise
4. Cron scheduling: Adjust the CRON_EXPRESSION to match your needs – less frequent for production, more frequent for testing

Important Notes

• Remember to add a space after your cron expressions to prevent script failures
• Keep your API keys secure and regularly rotate them
• Consider implementing different scheduling patterns for event-based and year-based organization
• Always verify your mount points and permissions before deploying

This setup provides a robust, automated way to organize your Immich photo library based on both events and yearly structures, while maintaining security and flexibility for multiple users.

https://github.com/Salvoxia/immich-folder-album-creator
https://claude.ai