Setting up the environment: the app

This page is for building the app (app/ and crates/) and testing it. For the server, see Setting up the environment: the server.

What you need

• Stable Rust. The project uses the 2024 edition of Rust, so you need a recent compiler.
• Node 22 and npm.
• On Linux, the system libraries that Tauri needs. On Debian and Ubuntu: libwebkit2gtk-4.1-dev, libxdo-dev, libssl-dev, libayatana-appindicator3-dev and librsvg2-dev, plus build-essential, curl, wget, file and pkg-config.
• For Android: JDK 17, the Android SDK (command-line tools, platform-tools, platform 36, build-tools 37) and the NDK, plus the Rust targets for Android (rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android).
• Docker, only if you want to regenerate the list of licences or work on the server.

On Windows and macOS, Tauri brings its system dependencies in another way (WebView2 on Windows); the Tauri guide explains them. The project is developed on Linux, and everything that follows is tested there.

With or without a container

The maintainer works inside a Distrobox container called library-dev, running Ubuntu 24.04. Why: Tauri 2 needs WebKitGTK 4.1, which does not exist on Ubuntu 20.04, the system on his machine; the container avoids upgrading the whole system. Distrobox shares the home folder, the network and the screen, so the code is edited with your usual editor and Tauri’s windows open as normal apps.

It is not the only way, and you do not need it. On a recent distribution (Ubuntu 22.04 or later, Fedora, Arch…) install the same packages directly and skip the container. If you want to reproduce the maintainer’s environment, docs/development/setup.md has every step (in Spanish): creating the container, installing packages, enabling Rust and Android only inside the container, and connecting a phone over wireless debugging.

In the project documentation, an app command can appear like this:

distrobox enter library-dev -- bash -ic '<command>'

The -i option is required because it loads the environment from ~/.bashrc. Without a container, run the command as it is.

Starting the app on the desktop

cd app
npm install
npm run tauri dev

It compiles the Rust core, opens the window and reloads the interface when you save a file.

To see only the interface in the browser, with invented data and without Rust, use npm run dev and open the address it prints with ?mock at the end (/?mock). It is the test mode the screenshots of the user guide use.

If you need a second instance with its own data (for example, to test sync over the home network with two “devices” on the same machine), debug builds have a variable that changes the data folder:

KOSMOTHEKA_DATA_DIR=/tmp/kosmotheka-b target/debug/kosmotheka

(with npm run tauri dev running beforehand, so that the binary exists).

Starting on Android

It is tested on a real phone, connected over wireless debugging (Android 11 or later) instead of USB:

1. On the phone: Developer options, “Wireless debugging”, “Pair device with pairing code”.
2. On your machine: adb pair IP:PORT CODE. Keep the phone’s dialog open until it finishes, or the code expires.
3. adb devices must list the phone. If not, adb connect IP:PORT with the port from the main “Wireless debugging” screen (not the pairing one).
4. From app/: npm run tauri android dev. It compiles, installs and opens the app, with reload.

To generate a debug APK:

cd app
npm run tauri android build -- --debug --apk --target aarch64

--target aarch64 compiles only for current 64-bit phones; without it, it compiles four architectures and takes four times as long. The Android project generated by Tauri (app/src-tauri/gen/android/) is in the repository: edit it with care.

The checks

Before sending a change, run the ones that match what you touched. Continuous integration (GitHub Actions) runs all of them.

Rust (from the root of the repository). app/dist must exist first, because Tauri embeds the compiled interface: run npm run build in app/ beforehand.

What for	Command
Format	cargo fmt --all --check (to fix, cargo fmt --all)
Compiler warnings	cargo clippy --all-targets -- -D warnings
Tests	cargo test
Licences and dependency advisories	cargo deny check
Declared and unused dependencies	cargo machete

cargo deny and cargo machete are installed with cargo install.

The interface (from app/):

What for	Command
Build	npm run build
Types	npm run typecheck
Style	npm run lint and npm run format:check (npm run format fixes)
Unused code	npm run knip
The version has a what’s-new line	npm run check:whats-new
The licence list covers what is shipped	npm run check:licenses

The specification (from app/): npm run check:spec checks the schema against the conformance cases, and npm run check:codes the rule for the second-factor code.

Tests with real services. The normal tests never use the network: they read recorded responses in app/src-tauri/tests/fixtures/. The ones that do need it are marked as ignored and their name starts with live_; they are run by hand with cargo test -p kosmotheka -- --ignored live_. The ignored ones named print_* generate those recorded responses, and they are only run when a format changes.

If you change a dependency that ships in the app, the list of licences is regenerated with npm run licenses. It needs Docker and network access.

If something fails

• Blank or grey window on Linux with an old kernel. If the log says that the container’s graphics driver is newer than the kernel supports (amdgpu: DRM version…), render WebKitGTK in software with LIBGL_ALWAYS_SOFTWARE=1 WEBKIT_DISABLE_COMPOSITING_MODE=1 WEBKIT_DISABLE_DMABUF_RENDERER=1. This is for development only.
• The first Android build fails at org.gradle.wrapper.Download. Your network may resolve IPv6 without having a route out. Force IPv4 once, until Gradle is cached: JAVA_TOOL_OPTIONS=-Djava.net.preferIPv4Stack=true npm run tauri android build -- --debug --apk --target aarch64.
• Desktop installers (npm run tauri build) only install on systems like the container’s or newer. The Windows one is produced by continuous integration.

Next step: How to contribute.