Pelagica

https://pelagica.app/docs
Admin
Pelagica is a fast, modern, and open-source web, desktop, and smart TV client for the Jellyfin media...
Tokens:6,662
Snippets:72
Trust Score:3.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Register TV with ares-setup-device and get key

Source: https://pelagica.app/docs/webos

Register the TV as an install target using the IP address and passphrase from the Developer Mode app, then retrieve the key with ares-novacom. The port is 9922 and the username is 'prisoner'.

```bash
ares-setup-device -a pelagica-tv -i "host=<TV_IP>" -i "port=9922" -i "username=prisoner" -i "passphrase=<PASSPHRASE>" -i "default=true"
ares-novacom --device pelagica-tv --getkey
```

--------------------------------

### Clone and start dev environment

Source: https://pelagica.app/docs/development

Clones the Pelagica repository and starts the full development environment with `task dev`. Dependencies are installed automatically on first run and whenever package.json, pnpm-lock.yaml, go.mod, or go.sum change.

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

task dev
```

--------------------------------

### Package and installer commands for macOS, Windows, and Linux

Source: https://pelagica.app/docs/desktop

Commands to package the app and create installers for each platform. Outputs are listed in the table. Requires platform-specific tools: create-dmg on macOS, NSIS on Windows, and GTK4/WebKitGTK dev headers on Linux.

```bash
task desktop:package:macos
```

```bash
task desktop:installer:macos
```

```bash
task desktop:package:windows
```

```bash
task desktop:installer:windows
```

```bash
task desktop:package:linux
```

```bash
task desktop:installer:linux:deb
```

```bash
task desktop:installer:linux:pkg
```

```bash
task desktop:installer:linux:appimage
```

--------------------------------

### Install webOS TV CLI

Source: https://pelagica.app/docs/webos

Install the official webOS TV CLI globally via npm. This is the first step in the command-line installation method.

```bash
npm install -g @webos-tools/cli
```

--------------------------------

### Install and launch Pelagica with ares-install and ares-launch

Source: https://pelagica.app/docs/webos

Install the downloaded pelagica-webos.ipk file on the registered TV and launch the app. The app ID is app.pelagica.pelagica.

```bash
ares-install -d pelagica-tv pelagica-webos.ipk
ares-launch app.pelagica.pelagica -d pelagica-tv
```

--------------------------------

### Create Pelagica directory

Source: https://pelagica.app/docs/web

Creates a directory named pelagica and changes into it, as the first step of the quick start.

```bash
mkdir -p pelagica && cd pelagica
```

--------------------------------

### Install Pelagica via Homebrew tap

Source: https://pelagica.app/docs/desktop

Adds the PelagicaApp/pelagica tap, trusts it, and installs the cask. Later updates use `brew upgrade --cask pelagica`.

```bash
brew tap PelagicaApp/pelagica
brew trust PelagicaApp/pelagica
brew install --cask pelagica
```

--------------------------------

### Run prebuilt /pelagica image with Docker run

Source: https://pelagica.app/docs/subpath

Starts the prebuilt -basepath image, which serves from /pelagica and cannot be reconfigured. The container is reachable at http://localhost:8080/pelagica.

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

--------------------------------

### Run individual components

Source: https://pelagica.app/docs/development

Runs the frontend (Vite dev server), backend (Go), or desktop app shell individually using Task. Each command starts only the specified component.

```bash
task frontend   # Vite dev server only
task backend    # Go backend only
task desktop    # Desktop app shell only
```

--------------------------------

### Run Pelagica container with docker run

Source: https://pelagica.app/docs/web

Starts the Pelagica container on port 8080, mounting the host config directory to /config and restarting unless stopped. Replace $(pwd)/config with the actual path where config files should be stored, e.g. /mnt/user/appdata/pelagica.

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

--------------------------------

### Docker run with SERVER_ADDRESS environment variable

Source: https://pelagica.app/docs/configuration

Forces Pelagica to connect to a specific Jellyfin instance by setting the SERVER_ADDRESS environment variable when starting the container. The address must be reachable from a user's browser, so use the public address of your Jellyfin server, not a local address like http://localhost:8096.

```bash
docker run -d \
    --name pelagica \
    -p 8080:80 \
    -v /path/to/config:/config \
    -e SERVER_ADDRESS=http://your-jellyfin-server:8096 \
    --restart unless-stopped \
    kartoffelchipss/pelagica:latest
```

--------------------------------

### Build desktop app with Task

Source: https://pelagica.app/docs/desktop

Builds the desktop app from source, producing a `desktop/bin/pelagica` binary.

```bash
task desktop:build
```

--------------------------------

### List all available tasks

Source: https://pelagica.app/docs/development

Displays all available Task commands for the project.

```bash
task --list
```

--------------------------------

### Run prebuilt /pelagica image with Docker Compose

Source: https://pelagica.app/docs/subpath

Docker Compose equivalent for the prebuilt -basepath image. Serves from /pelagica and mounts ./config to /config.

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

--------------------------------

### Build custom path image with Docker Compose

Source: https://pelagica.app/docs/subpath

Docker Compose build configuration for a custom BASE_PATH. After building, run with docker compose up -d --build.

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

```bash
docker compose up -d --build
```

--------------------------------

### Build custom path image with Docker build

Source: https://pelagica.app/docs/subpath

Builds a Pelagica image with a custom BASE_PATH build argument, e.g. /media/pelagica. The path is baked into the image at build time.

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

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

--------------------------------

### Docker Compose configuration for Pelagica

Source: https://pelagica.app/docs/web

Create a docker-compose.yml file to run Pelagica with Docker Compose. Maps port 8080 to 80, mounts ./config to /config, and sets restart policy to unless-stopped. Replace ./config with a persistent path.

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

--------------------------------

### Clone the Pelagica Apple TV repository

Source: https://pelagica.app/docs/appletv

Clone the pelagica-atv repository and navigate into the project directory. Requires Xcode 26 or later and targets tvOS 26.5.

```bash
git clone https://github.com/PelagicaApp/pelagica-atv.git
cd pelagica-atv
```

--------------------------------

### Reverse proxy configuration for /pelagica

Source: https://pelagica.app/docs/subpath

nginx location block that forwards the /pelagica prefix to the container without stripping it. The container's nginx expects the full path.

```nginx
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;
}
```
Tokens:
Raw