Running Under a Subpath

If you want to publish Pelagica under a subpath on a host you already use for something else (for example https://media.example.com/pelagica, alongside Jellyfin on the same domain), a normal Pelagica image won’t work: it expects to be served from /. Pelagica publishes a separate image variant with the path baked in at build time for this.

Using the prebuilt /pelagica image

The -basepath tagged image is prebuilt to serve from /pelagica and can’t be reconfigured to another path. If /pelagica works for you, use it directly:

docker run -d \
    --name pelagica \
    -p 8080:80 \
    -v "$(pwd)/config:/config" \
    --restart unless-stopped \
    kartoffelchipss/pelagica:latest-basepath

Or with Docker Compose:

services:
    pelagica:
        image: kartoffelchipss/pelagica:latest-basepath
        container_name: pelagica
        ports:
            - '8080:80'
        volumes:
            - ./config:/config
        restart: unless-stopped

Pelagica is now reachable at http://localhost:8080/pelagica.

Pointing a reverse proxy at it

Forward the /pelagica prefix to the container without stripping it. The container’s own nginx expects to see it:

location /pelagica/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Because proxy_pass has no path of its own here, nginx forwards the full request URI (including /pelagica/) to the container, which is what the container’s routing and API calls expect.

Building your own path

/pelagica is hardcoded into the prebuilt -basepath image. There’s no build with a different path already published. To serve Pelagica from another subpath (e.g. /media/pelagica), build the image yourself with a BASE_PATH build argument:

git clone https://github.com/PelagicaApp/pelagica.git
cd pelagica

docker build --build-arg BASE_PATH=/media/pelagica -t pelagica:custom-path .

With Docker Compose:

services:
    pelagica:
        build:
            context: .
            args:
                BASE_PATH: /media/pelagica
        container_name: pelagica
        ports:
            - '8080:80'
        volumes:
            - ./config:/config
        restart: unless-stopped

docker compose up -d --build

Then run it the same way as the prebuilt image, and point your reverse proxy location block at whatever path you chose instead of /pelagica.