Codakey
Play
← Back to immich

How to Deploy & Use immich

Immich Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using Immich, a high-performance self-hosted photo and video management solution.

Prerequisites

Before you begin, ensure you have the following installed:

Installation

Immich primarily uses Docker Compose for deployment.

  1. Clone the Repository:

    git clone https://github.com/immich-app/immich.git
cd immich

  2. Prepare Environment Files: Immich uses .env files for configuration. Copy the example environment files:

    cp .env.example .env
cp docker-compose.yml.example docker-compose.yml

    Note: It's crucial to review and customize these files based on your setup.

  3. Pull Docker Images:

    docker compose pull

  4. Start Immich:

    docker compose up -d

    This command will start all Immich services in detached mode.

Configuration

Immich's configuration is primarily managed through the .env file and docker-compose.yml.

Environment Variables (.env)

Edit the .env file to configure Immich. Key variables include:

  • UPLOAD_LOCATION: Path to store your photos and videos. Ensure this path is correctly mapped as a volume in docker-compose.yml.
  • DB_HOSTNAME, DB_USERNAME, DB_PASSWORD, DB_DATABASE: PostgreSQL database connection details.
  • JWT_SECRET: A strong, randomly generated secret for JWT authentication.
  • TYPESENSE_API_KEY: API key for Typesense search.
  • MACHINE_LEARNING_HOST: Host for the machine learning service.

Docker Compose (docker-compose.yml)

The docker-compose.yml file defines the services, networks, and volumes for Immich.

  • Volumes: Ensure that the UPLOAD_LOCATION you set in .env is correctly mounted as a volume for the immich-server and immich-microservices containers. For example: 
    volumes:
  - ./upload:/usr/src/app/upload
    Where ./upload is the host path and /usr/src/app/upload is the container path.
  • Ports: By default, Immich services expose ports. Adjust them if necessary to avoid conflicts.
    • immich-server: 2283:3001 (API)
    • immich-web: 80:80 (Web UI)
  • Database: Immich uses PostgreSQL. The docker-compose.yml typically includes a PostgreSQL service. Ensure its data volume is persistent.

Database Migrations

Immich uses Kysely for database migrations. The application handles migrations automatically on startup. If you encounter issues during an upgrade from an older TypeORM-based Immich instance, you might see an error like ErrorMessages.TypeOrmUpgrade. Refer to the official Immich documentation for specific upgrade paths.

Build & Run Locally

Immich is built using TypeScript. While the primary deployment method is Docker, developers might need to build and run components locally.

Development Setup

  1. Install Node.js: Ensure you have Node.js (LTS recommended) installed.
  2. Install Dependencies: Navigate to the specific service directory (e.g., server/, web/, mobile/) and install dependencies: 
    cd server
npm install
  3. Run Services: Each service typically has a start:dev script. For example, to run the server in development mode: 
    cd server
npm run start:dev
    This will usually include hot-reloading for development.

Production Build

To build Immich for production without Docker:

  1. Build Server: 
    cd server
npm install
npm run build
  2. Build Web: 
    cd web
npm install
npm run build
    The built artifacts will be in a dist or build directory within each service. You would then need to configure a web server (like Nginx) to serve the web UI and proxy requests to the Immich API.

Deployment

The recommended and most straightforward deployment method for Immich is using Docker Compose.

  1. Server Requirements:

    • CPU: Immich can be CPU-intensive, especially during initial asset processing (thumbnails, facial recognition, smart search). A modern multi-core CPU is recommended.
    • RAM: At least 8GB RAM is recommended, more for larger libraries.
    • Storage: Ample storage for your photos and videos, plus SSD for the database and application files for better performance.
    • Network: Stable network connection for accessing the web UI and mobile apps.

  2. Deployment Steps (Docker Compose): Follow the "Installation" steps above to clone the repository, configure .env and docker-compose.yml, and then run:

    docker compose up -d

  3. Access Immich: Once the containers are running, you can access the Immich web interface by navigating to http://localhost (or the IP address/domain of your server) in your web browser.

  4. Mobile App Configuration: For the mobile app, set the Server Endpoint URL to http://your-server-ip-or-domain:2283 (or the port you configured for the immich-server).

Recommended Platforms

  • Self-hosted Server (Linux VM/Bare Metal): This is the most common and recommended deployment method using Docker Compose. It provides full control over your data and resources.
  • NAS (Network Attached Storage): Many NAS devices support Docker, making them suitable for Immich deployment, especially for leveraging existing storage.
  • Cloud VMs (AWS EC2, Google Cloud, Azure): For those who prefer cloud infrastructure, a Linux VM can host Immich using Docker Compose. Ensure you configure appropriate security groups and persistent storage.

Troubleshooting

Here are some common issues and their solutions:

  • ErrorMessages.TypeOrmUpgrade during startup:

    • Issue: This error indicates that your database contains TypeORM migrations from an older Immich version that are incompatible with the current Kysely-based migration system.
    • Solution: Do not attempt to run Kysely migrations directly on a database that has incomplete TypeORM migrations. You must follow the official Immich upgrade path from your specific previous version. Consult the Immich documentation on upgrading for the correct procedure, which often involves specific steps to bridge the migration gap.

  • Containers fail to start:

    • Check Docker Logs: Use docker compose logs to view the logs of failing containers. This often provides specific error messages.
    • Port Conflicts: Ensure no other applications are using the ports Immich is trying to bind (e.g., 80, 2283).
    • Resource Limits: Verify your server has enough RAM and CPU.
    • .env Configuration: Double-check all variables in your .env file, especially database credentials and paths.

  • "502 Bad Gateway" or "Connection Refused" when accessing the web UI:

    • immich-server not running: The API backend might not be running. Check docker compose ps and docker compose logs immich-server.
    • Incorrect immich-web configuration: Ensure the web service is correctly configured to proxy requests to the API.
    • Firewall: Check if your server's firewall is blocking access to the Immich ports.

  • Assets not appearing after upload:

    • UPLOAD_LOCATION: Verify that the UPLOAD_LOCATION in your .env file is correct and that the corresponding volume mount in docker-compose.yml is correctly configured and accessible by the containers.
    • Permissions: Ensure the Docker user has read/write permissions to the UPLOAD_LOCATION directory on your host system.
    • Microservices: Check the logs of immich-microservices for any errors related to asset processing.

  • Slow performance:

    • Hardware: Consider upgrading CPU, RAM, or using SSD storage for the database and asset files.
    • Database: Ensure your PostgreSQL database is running efficiently.
    • Machine Learning: If facial recognition or smart search is slow, check the immich-machine-learning service logs and ensure it has sufficient resources.

  • Unable to log in to the mobile app:

    • Server Endpoint URL: Confirm the Server Endpoint URL in the mobile app settings is correct (e.g., https://your-domain.com or http://your-server-ip:2283).
    • Network Access: Ensure your mobile device can reach the server. Check firewall rules.

For further assistance, refer to the official Immich documentation or join the Immich Discord server.

← Project overviewView alternatives to immich →