Install

This page is for the person who will run Evey for the household. You need a computer or a NAS that stays on, with Docker installed. It takes three steps:

1. Save one file, the compose file.
2. Start Evey with one command.
3. Open Evey in a browser.

Then the First setup wizard takes over.

Evey runs as a single container. Its database and search engine are inside it, so there is nothing else to install, no .env file to write, and no memory or CPU setting.

Use the file on this page, not the one in the Git repository

The docker-compose.yml at the root of the Git repository is a different setup, for developers and advanced installs: it needs a .env file and runs extra services. It is described in Advanced deployments.

What you need

• A computer or NAS that stays on, with an x86-64 processor (Intel or AMD). ARM64 machines need a release tag, which does not exist yet: see ARM hosts.
• Docker with Compose v2. The command is docker compose, with a space, not the older docker-compose.
• Your media folder: where your films, series, music or photos are.
• Some disk space for Evey's own data (database, artwork, search index). The compose file below keeps it in a folder named evey-data, next to the file.

Evey answers in plain HTTP on your home network. Watching from outside your home needs HTTPS, which you can add later: Remote access and HTTPS.

Step 1: Save the compose file

Create a folder for Evey, for example evey, and save this file in it as docker-compose.yml. Change one line: the path to your media (the line marked 5). For example, if your films are in /srv/media, the line becomes - /srv/media:/media.

docker-compose.yml

services:
  evey:
    image: eveyproject/evey:latest # (1)!
    container_name: evey-server
    ports:
      - "9091:9091" # (2)!
    volumes:
      - ./evey-data:/data # (3)!
      - evey-cache:/cache # (4)!
      - /path/to/your/media:/media # (5)!
    stop_grace_period: 60s # (6)!
    restart: unless-stopped

volumes:
  evey-cache:

1. The version of Evey. latest is the newest release. To stay on a given version, use a release tag such as 0.1.0, or a sha-<commit> tag: see Backups and updates.
2. The port. The number on the left is the one you will type in the browser and in the apps. Keep 9091 unless another program already uses it.
3. Evey's own data: database, keys, generated passwords, search index, artwork, logs, backups, plugins. This is the folder to back up.
4. A cache of converted video, resized photos and music covers. It can be deleted at any time and fills up again by itself. The poster variants are not in it: they live under evey-data/artworks.
5. Your media. Replace /path/to/your/media with the real folder. Inside Evey, this folder is called /media. It is writable on purpose, so that Media health can repair a file when you ask. Add :ro at the end to make it read-only: Evey then cannot write there, and repairs fail.
6. Gives the database time to stop cleanly when the container stops. Docker's default of 10 seconds is short for a large collection.

Step 2: Start Evey

In a terminal, in the folder that holds the file:

docker compose up -d

Evey starts in the background. To watch what it is doing, run docker compose logs -f evey; press Ctrl+C to stop watching, Evey keeps running.

On the first start, Evey creates its passwords and its database in evey-data. You have nothing to prepare.

Step 3: Open Evey in a browser

The address is http://, then the address of the machine running Docker, then :9091:

Where your browser is	Address to type
On the machine running Docker	http://localhost:9091
On another computer or a phone at home	http:// + the IP address of the machine running Docker + :9091, for example http://192.168.1.20:9091
Outside your home	Not yet. This needs HTTPS and a public address: see Remote access and HTTPS.

To find the IP address of the machine running Docker, look in your router's list of connected devices, or run ip a on Linux, ipconfig on Windows, ifconfig on macOS. If you changed the port in step 1, use the number on the left of the ports: line instead of 9091.

The first time, the address opens the setup wizard. Continue with First setup. Once the wizard is done, the same address opens the sign-in page.

Write this address down

Everyone at home will need it. The Android and Android TV apps ask for exactly this address on their first screen, with http:// and the port: Connect the apps.

Where your data lives

Location	What it holds	Can you delete it?
./evey-data	Database, keys, generated passwords, search index, timeline thumbnails, artwork, logs, backups, plugins	No. Losing it loses every account, watch history and setting. The only exception is meili/ inside it, the search index: the command evey admin reindex-search rebuilds it from the database.
evey-cache volume	Converted video, resized photos and music covers (poster variants are in evey-data/artworks)	Yes. It fills up again by itself.
Your media folders	Your files	Evey never deletes them. Removing a title in Evey removes it from the library, not from the disk.

Evey writes into your media folders in three cases only:

• a repair you start from Media Health (the original is kept as a backup);
• a subtitle downloaded from OpenSubtitles (saved in a .subtitles folder next to the film);
• a small test file, deleted right after, that checks Evey still notices new files.

Common changes

Each of these is a few lines in the same file.

A second media folder. Add - /other/path:/media2 under volumes:. A third one is /media3, and so on.

A second Evey on the same host. Give it another container_name and other host ports, otherwise docker compose up refuses to start (the name is already in use).

Another port. Change only the number on the left, for example "8080:9091". Then type :8080 in the browser and in the apps.

Who owns the files. By default, Evey adopts the owner of your media folder, so that repairs can write. To choose yourself, add PUID and PGID under environment:, with the numbers given by id -u and id -g. The container starts as root only to apply this; Evey itself never runs as root.

A graphics card for video conversion. Give the container access to the card: see Hardware acceleration.

Which version you run. The image: line decides:

image:	You get
eveyproject/evey:latest	the newest release, each docker compose pull moves you to the next one
eveyproject/evey:0.1	the newest fix of that minor line (0.1.0, 0.1.1, ...), never a new minor
eveyproject/evey:0.1.0	exactly that release, until you change the line
eveyproject/evey:sha-<commit>	one exact build, the only tag that never moves
eveyproject/evey:master	the development branch, rebuilt at every push: for testing, not for a server you rely on

Release numbers follow semantic versioning and start at 0.1.0; the 0.x line is the public beta. To change version, edit the line, then docker compose pull && docker compose up -d; your data stays in ./evey-data. The running version shows in Admin → Dashboard, at /healthz, and with docker exec evey-server evey version. A tag without a suffix is the full image, with every plugin runtime (Python, Node.js, PHP, Ruby and Lua); -nodejs and -lean are slimmer builds with fewer of them (details).

You already run a reverse proxy (a program that puts HTTPS in front of your services): see Remote access and HTTPS.

On a NAS (Synology Container Manager, QNAP Container Station)

• Create the evey-data folder before the first start. These interfaces refuse to mount a folder that does not exist, unlike the Docker command line. Nothing else needs creating.
• Set PUID and PGID to the NAS user that owns the media (id <user> over SSH; on Synology usually around 1026, group 100). NAS shares are often owned by root, which Evey never adopts on its own.
• Intel NAS with Quick Sync: add the devices: and group_add: lines described in Hardware acceleration.

What Evey sets up by itself

You do not configure these:

• How much video the server can convert at once. It measures the machine at its first quiet moment.
• The graphics card. Evey detects the card you gave the container and checks it with a real conversion.
• How each device plays a file. Decided for each playback: see How playback is decided.
• Access from outside your home. Off until you give the server a public address.

Settings that you may change later (server name, schedules, limits, API keys) are in the admin panel, not in the compose file. The few environment variables that exist are listed in the Configuration reference.