Self-Hosting a Photo and Video Management Solution: A Developer's Guide to Immich
Self-Hosting & Control
You get full ownership and control of your data. This is crucial for privacy and security. You can run it on your own server, a Raspberry Pi, or even a Kubernetes cluster.
Modern Architecture
Immich uses a microservices architecture. The front end is a mobile app and a web app, the backend is written in Node.js/TypeScript, and it uses a bunch of other services like Redis and PostgreSQL. This setup is a great example of modern application design.
API-First Design
The core of Immich is its RESTful API. This means you can programmatically interact with your photo library. You can upload photos, search for images, create albums, and more, all with code. This opens up possibilities for automation and custom integrations.
Open Source
The entire project is open source. You can dive into the code, understand how it works, and contribute to the project. It's a fantastic learning opportunity, especially for Node.js, TypeScript, and mobile development.
Community & Extensibility
There's a vibrant community around Immich. You can build plugins, scripts, or even entirely new front ends that use the Immich API. This extensibility is a huge plus for engineers who like to tinker.
The easiest way to get Immich up and running is with Docker and Docker Compose. It handles all the dependencies for you, including the database, microservices, and background workers.
Docker and Docker Compose installed on your machine.
A server with at least 4GB of RAM for a smooth experience, more if you have a huge library.
Clone the Repository
Start by cloning the Immich repository from GitHub.
git clone https://github.com/immich-app/immich.git
cd immich
Copy the .env file
The repository provides an example environment file.
cp .env.example .env
Configure .env
Open the .env file and set a strong password for your database. You can also change the ports if needed.
Run with Docker Compose
Execute the following command to start all the services. This will take some time the first time you run it as it needs to pull all the necessary Docker images.
docker-compose up -d
Access the Web UI
Once everything is running, open your browser and navigate to http://localhost:2283 (or the port you configured). Follow the on-screen instructions to create your first user account.
Let's look at a simple example of using the Immich API to upload a photo. You could use this in a custom script or a client application. This example uses curl for simplicity, but you could easily use a library like axios in a Node.js application.
An API key generated from your Immich user settings.
The path to the image file you want to upload.
# Replace with your actual values
API_KEY="YOUR_IMMICH_API_KEY"
SERVER_URL="http://localhost:2283"
IMAGE_PATH="./my_vacation_photo.jpg"
curl -X POST \
-H "x-api-key: ${API_KEY}" \
-F "assetData=@${IMAGE_PATH}" \
"${SERVER_URL}/api/asset/upload"
This command makes a POST request to the /api/asset/upload endpoint. The -H flag sets the API key in the header for authentication. The -F flag is for a multipart/form-data request, where @${IMAGE_PATH} tells curl to read the file and include it in the request body.
A successful response will return a JSON object with details about the newly uploaded asset, including its ID, filename, and other metadata.
{
"id": "c1f727c9-4b2e-4b77-8d0f-4e924c53d49e",
"deviceAssetId": "..."
// other asset information
}
