Development
Dev environment
Run the engine, the server, the client and PostgreSQL locally, work with sqlx migrations, run the test suites, and build the mobile, TV and desktop clients.
Prerequisites#
- Docker and Docker Compose, for the recommended local stack.
- A checkout of fliks-engine next to this repository
(
../fliks-engine, or setFLIKS_ENGINE_SRC): the dev stack builds and runs the engine from it. - Rust, the version pinned in
rust-toolchain.toml(installed byrustupon first build), to build or test the server on the host. - Node.js 24, the version the Docker images and most CI jobs use, for the client. There is no
.nvmrc; the Angular CLI accepts^22.22.3,^24.15.0or>=26, so odd-numbered releases such as 23 or 25 won't work. TypeScript and the Angular CLI come withnpm ci, nothing needs a global install. - A local PostgreSQL if you'd rather not use Docker for the database.
- git.
Quick start with Docker#
docker-compose.dev.example.yml, at the repo root, runs the engine, the server and the client in
watch mode against a PostgreSQL container.
cp docker-compose.dev.example.yml docker-compose.yml
docker compose upThis starts four services, mirroring production:
postgres: PostgreSQL 18, with a named volume.engine:fliks-enginebuilt from../fliks-enginewithcargo watch, the front door on port 3000. It forwards the whole HTTP API toserver. The first build takes minutes.server:fliks-serverrebuilt bycargo watchfrom./server, on port 3001 (no published port, it sits behind the engine).client: the Angular dev server on port 4500, bind-mounted from./client, proxying/apito the engine.
Open http://localhost:4500. A fresh database shows the setup page: create the administrator
there. Media, downloads and data live under ./.dev/ (medias, downloads, data); put test
media in ./.dev/medias. Rebuild the client image (docker compose build client) whenever its
package.json changes, since dependencies live inside the image and not on the bind mount.
To pass through a GPU for hardware transcoding (Intel QSV/VAAPI), uncomment the devices and
group_add lines for the engine service and set FLIKS_RENDER_GID to your host's render
group id (getent group render | cut -d: -f3).
To build the server against a local engine checkout instead of the pinned release, run
scripts/bump-engine.sh --local ../fliks-engine. scripts/bump-engine.sh <version> moves the
pinned release: it rewrites engine.lock, the engine image in the Dockerfile and the engine tag
of server/crates/server/Cargo.toml together, and the engine-lock.yml check fails a pull request
where they disagree.
Quick start without Docker#
The server and the client run on the host; playback needs the engine, which the Docker stack
provides (without one, playback-info answers 503).
Start a PostgreSQL with the credentials the server defaults to (
fliks/fliks, databasefliks). For example:bashdocker run --name fliks-postgres -d \ -e POSTGRES_USER=fliks -e POSTGRES_PASSWORD=fliks -e POSTGRES_DB=fliks \ -p 5432:5432 postgres:18-alpineServer, from
server/:bashcd server PORT=3001 SQLX_OFFLINE=true cargo run -p fliks-serverPending migrations run at start. See Environment variables for
DB_*and the rest. Set the TMDB and TVDB keys in Settings > Plugins.Client, in another terminal:
bashcd client npm ci npm startnpm startisng serveonhttp://localhost:4200; its dev proxy (client/proxy.conf.json) forwards/apitohttp://localhost:3001.Open
http://localhost:4200. On an empty database the client shows the setup page where you create the administrator.
Migrations#
The schema is owned by the sqlx migrations in server/migrations/, one .sql file per change
named <timestamp>_<name>.sql. The server applies the pending ones at every start;
fliks-server migrate applies them without serving, and refuses a database it can't adopt.
To change the schema, add a migration file, then refresh the query cache the build reads
(server/.sqlx, checked in CI) with cargo sqlx prepare --workspace -- --all-targets, with
DATABASE_URL pointing at the migrated database.
A 4.x database is adopted from its TypeORM migration ledger on first start. A dev database built
by the old TypeORM synchronize has an empty ledger and fliks-server migrate refuses it: re-baseline
it once, from the repo root (dc is docker compose -f docker-compose.yml):
dc stop server
dc exec -T postgres sh -c 'pg_dump -U $POSTGRES_USER -Fc -T migrations $POSTGRES_DB' > .dev/fliks.dump
dc exec postgres sh -c 'dropdb -U $POSTGRES_USER $POSTGRES_DB && createdb -U $POSTGRES_USER $POSTGRES_DB'
dc run --rm server cargo run -p fliks-server -- migrate
echo "SELECT 'TRUNCATE ' || string_agg(format('%I', tablename), ',') || ' CASCADE' FROM pg_tables WHERE schemaname = 'public' AND tablename <> '_sqlx_migrations' \gexec" | dc exec -T postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'
dc exec -T postgres sh -c 'pg_restore -U $POSTGRES_USER -d $POSTGRES_DB --data-only --disable-triggers -n public' < .dev/fliks.dump
dc exec -T postgres sh -c 'pg_restore -U $POSTGRES_USER -d $POSTGRES_DB -N public' < .dev/fliks.dump # plugin schemas, schema and data
dc up -dThe TRUNCATE clears rows seeded by migrations. Expect pg_restore errors only for tables dropped
by later migrations and their sequences, plus migrations_id_seq.
Tests#
The server has unit tests in fliks_domain and integration tests in fliks-server
(server/crates/server/tests/). The database tests need PostgreSQL, so run them through
scripts/with-test-postgres.sh, which starts a throwaway PostgreSQL 18 container and removes it
on exit. From server/:
cargo test -p fliks_domain
../scripts/with-test-postgres.sh cargo test -p fliks-server
cargo fmt --all --check
cargo clippy --all-targets -- -D warningsThe plugin SDK (server/crates/plugin-sdk) is a separate workspace with its own tests. The HTTP
parity suite replays recorded scenarios through the front door and runs locally only; see
server/parity/README.md.
A behaviour change updates its spec in server/docs/spec/, the parity expects and the golden
vectors in the same pull request. If you add or change a route, regenerate server/openapi.json
with fliks-server openapi > openapi.json: CI fails when it drifts.
The client uses Vitest (with jsdom) through the
Angular CLI's unit-test builder. From client/:
npm test # ng test, watches for changes in a terminal
npm test -- --watch=false # a single runThe desktop package has its own tests on Node's built-in runner, plus a typecheck: npm test and
npm run typecheck from desktop/.
CI runs these suites on pull requests (server.yml, client.yml); see
Contributing for everything CI checks.
Building the other clients#
From client/, the same build a target ships is one npm script away:
| Target | Command | Notes |
|---|---|---|
| Android (Capacitor) | npm run cap:build |
Builds the Angular app, then npx cap sync android. Open the project in Android Studio with npm run cap:open. |
| iOS (Capacitor) | npm run cap:build:ios |
Same, opened with npm run cap:open:ios. Needs a Mac with Xcode. |
| Samsung TV (Tizen) | npm run tizen:build |
Builds against a Chromium 85 browserslist target, then packages an unsigned .wgt. Signing it and installing it on a TV go through the Tizen Studio CLI (tizen package, tizen install), see client/tizen/README.md. |
| LG TV (webOS) | npm run webos:build |
Same Chromium 85 target, packages an .ipk. Install it with the webOS CLI (ares-install). |
From desktop/ (first-time setup, the native addon and the vendored
libmpv, is in desktop/README.md):
npm run dev:linux # dev run on Linux, the primary dev platform for this client
npm run dist:linux # AppImage / .deb
npm run dist:mac # .dmg / .zip
npm run dist:win # NSIS installerThe native platform shells that run the server itself, the Windows tray
app and the macOS menu-bar app, and the native tvOS app, use their own
toolchains (.NET, Xcode/XcodeGen) instead of npm scripts. Their build
steps are documented in windows/README.md, macos/README.md and
appletv/README.md.