Stump

https://www.stumpapp.dev/docs
Admin
Stump is an open source, self-hostable media server for digital books (ebooks, comic books, manga,...
Tokens:17,991
Snippets:346
Trust Score:7.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start Stump Container

Source: https://www.stumpapp.dev/docs/getting-started/installation/docker

Commands to start the container after creation.

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

```bash
docker start stump
```

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

### Initialize development environment

Source: https://www.stumpapp.dev/docs/developer/contributing

Run this command after installing required dependencies to set up the project.

```bash
yarn run setup
```

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

### Launch Storybook for Component Development

Source: https://www.stumpapp.dev/docs/developer/contributing

Starts the Storybook development server to preview and interact with the custom component library.

```bash
yarn storybook
```

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

### Install Stump on Arch Linux

Source: https://www.stumpapp.dev/docs/getting-started/installation/source

Installs the Stump package from the AUR using an AUR helper like yay.

```bash
yay -S stump
```

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

### Windows Service Configuration

Source: https://www.stumpapp.dev/docs/getting-started/installation/binaries

Example configuration file for running Stump as a background service on Windows.

```ini
[Unit]
Description=Stump Book Server
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=1
User=stump
WorkingDirectory=/opt/stump
ExecStart=cargo run -p stump_server --release

[Install]
WantedBy=multi-user.target
```

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

### Build Stump locally

Source: https://www.stumpapp.dev/docs/getting-started/installation/source

Compiles the web application and the server binary. Ensure dependencies are installed before running this command.

```bash
yarn web build && cargo build --package stump_server --release
```

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

### Run Stump development services

Source: https://www.stumpapp.dev/docs/developer/contributing

Commands to start the web application, desktop application, or documentation website.

```bash
# run the webapp + server
yarn dev:web
# run the desktop app + server
yarn start:desktop
# run the docs website
yarn docs dev
```

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

### Configure Zitadel OIDC via Docker Compose

Source: https://www.stumpapp.dev/docs/guides/access-control/oidc

Example configuration for integrating Zitadel with Stump using environment variables.

```yaml
services:
  stump:
    image: aaronleopold/stump:latest
    environment:
      STUMP_OIDC_ENABLED: 'true'
      STUMP_OIDC_ISSUER_URL: 'https://your-zitadel-instance.com'
      STUMP_OIDC_CLIENT_ID: 'your-zitadel-client-id'
      STUMP_OIDC_CLIENT_SECRET: 'your-zitadel-client-secret'
      STUMP_OIDC_EXTRA_AUDIENCES: 'your-zitadel-project-id'
    ports:
      - '10801:10801'
```

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

### OPDS v2.0 Search URL Template Example

Source: https://www.stumpapp.dev/docs/apps/mobile/servers/opds-compatibility

An example of a templated search URL used by some OPDS servers to allow targeted search queries.

```text
/opds/v2.0/search{?query,author,title,subject}
```

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

### Configure OIDC via Environment Variables

Source: https://www.stumpapp.dev/docs/guides/access-control/oidc

Standard Docker Compose setup for OIDC authentication using environment variables.

```yaml
services:
  stump:
    image: aaronleopold/stump:latest
    environment:
      STUMP_OIDC_ENABLED: 'true'
      STUMP_OIDC_ISSUER_URL: 'https://auth.example.com/application/o/stump/'
      STUMP_OIDC_CLIENT_ID: 'stump-client-id'
      STUMP_OIDC_CLIENT_SECRET: 'super-secret-value'
      # Optional settings (and their defaults)
      # STUMP_OIDC_SCOPES: 'openid,email,profile'
      # STUMP_OIDC_ALLOW_REGISTRATION: 'true'
      # STUMP_OIDC_DISABLE_LOCAL_AUTH: 'false'
    ports:
      - '10801:10801'
```

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

### Authelia OIDC YAML Configuration

Source: https://www.stumpapp.dev/docs/guides/access-control/oidc

Example YAML configuration for integrating Authelia as an OIDC provider with Stump.

```yaml
identity_providers:
  oidc:
    # --------------------------------------------------------------------------
    # Security Configuration
    # --------------------------------------------------------------------------
    # HMAC secret used for signing tokens (store as plain text, not hashed)
    # Recommended to not store directly in YAML, this is just for example purposes
    hmac_secret: 'supersecret1'
    # --------------------------------------------------------------------------
    # JSON Web Key Set (JWKS) Configuration
    # --------------------------------------------------------------------------
    jwks:
      - algorithm: 'RS256'
        use: 'sig'
        # Private key in PEM DER format (store as plain text, not hashed)
        # Replace with your actual RSA private key
        # Recommended to not store directly in YAML, this is just for example purposes
        key: '-----BEGIN RSA PRIVATE KEY-----'
    # --------------------------------------------------------------------------
    # Claims Policies
    # --------------------------------------------------------------------------
    # Describes how claims are mapped from the identity provider to Stump
    claims_policies:
      stump_policy:
        id_token:
          - 'email'
          - 'name'
    # --------------------------------------------------------------------------
    # Token Lifespans
    # --------------------------------------------------------------------------
    lifespans:
      access_token: '1 hour'
      authorize_code: '1 minute'
      id_token: '1 hour'
      refresh_token: '90 minutes'
    # --------------------------------------------------------------------------
    # OAuth/OIDC Clients
    # --------------------------------------------------------------------------
    clients:
      - client_id: 'Stump_OIDC' # Corresponds to STUMP_OIDC_CLIENT_ID
        client_name: 'Stump'
        # Client secret (stored hashed in the system)
        # Recommended to not store directly in YAML, this is just for example purposes
        client_secret: 'supersecret2' # Corresponds to STUMP_OIDC_CLIENT_SECRET
        redirect_uris:
          - 'https://stump.example.com/api/v2/auth/oidc/callback'
        claims_policy: 'stump_policy'
        consent_mode: 'implicit'
```

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

### Display CLI help information

Source: https://www.stumpapp.dev/docs/developer/cli

Use this command to list all available subcommands and global options for the Stump executable.

```bash
./stump --help
```

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

### Display subcommand help information

Source: https://www.stumpapp.dev/docs/developer/cli

Use this command to view specific documentation and options for a particular subcommand.

```bash
./stump <subcommand> --help
```

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

### Run the Stump Server

Source: https://www.stumpapp.dev/docs/getting-started/installation/binaries

Commands to launch the Stump server executable on different operating systems.

```bash
# Navigate to the folder containing the stump binary, e.g., ~/Stump, or be sure to include the full path to the binary
./stump_server
```

```cmd
# Navigate to the folder containing the stump binary, e.g., C:\Stump, or be sure to include the full path to the binary
stump_server.exe
```

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

### Stump Instance Directory Structure

Source: https://www.stumpapp.dev/docs/guides/breaking-changes/0.1.0

Recommended directory layout for maintaining isolated old and new Stump instances during migration.

```bash
/stump-old/      # Your existing Stump instance
	├── docker-compose.yml
	└── config/
	    └── stump.db
/stump-new/      # Your new Stump instance
	├── docker-compose.yml
	└── config/ # Empty, first start will create what you need
```

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

### Initialize the Stump SDK with an API key

Source: https://www.stumpapp.dev/docs/guides/features/api-keys

Configure the SDK instance to automatically include the API key in request headers.

```typescript
import { Api } from '@stump/sdk'

// Create a new SDK instance, passing in your API key
const sdk = new Api({
	baseURL: 'https://my-stump.cloud',
	authMethod: 'api-key',
	apiKey: '<your_api_key>',
})

// Now you can make requests
const library = await sdk.library.get({ name: ['Ebooks'] })
```

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

### Run Stump Migration CLI

Source: https://www.stumpapp.dev/docs/guides/breaking-changes/0.1.0

Command to execute the migration tool within the new Stump container.

```bash
# If using Docker, exec into the NEW stump container
./stump system sea-orm-migration
```

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

### Configure Stump with Docker Compose

Source: https://www.stumpapp.dev/docs/getting-started/installation/docker

A template for a docker-compose.yml file to bootstrap the Stump server.

```yaml
services:
  stump:
    image: aaronleopold/stump:latest
    container_name: stump
    # Replace my paths (prior to the colons) with your own
    volumes:
      - /home/aaronleopold/.stump:/config
      - /media/books:/data
    ports:
      - 10801:10801
    environment:
      - PUID=1000
      - PGID=1000
      # This `environment` field is optional, remove if you don't need it.
      # I am using it as an example here, but it's actually a default value.
      - STUMP_CONFIG_DIR=/config
    restart: unless-stopped
```

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

### Run Stump server with Cargo

Source: https://www.stumpapp.dev/docs/developer/contributing

Directly execute the server package using the Rust cargo tool.

```bash
cargo run --package stump_server --bin stump_server
```

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

### Configure OIDC via TOML File

Source: https://www.stumpapp.dev/docs/guides/access-control/oidc

Configuration format for the Stump.toml file, requiring the [oidc] table section.

```toml
# other configurations...
port = 10801

[oidc]
enabled = true
issuer_url = "https://auth.example.com/application/o/stump/"
client_id = "stump-client-id"
client_secret = "super-secret-value"
scopes = "openid,email,profile"
allow_registration = true
disable_local_auth = false
```

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

### Configure Kobo eReader endpoint

Source: https://www.stumpapp.dev/docs/guides/integrations/kobo

Update the Kobo eReader configuration file to redirect the API endpoint to your Stump server instance.

```ini
api_endpoint=https://storeapi.kobo.com
```

```ini
api_endpoint=http(s)://your-server(:{port})(/{baseUrl})/kobo/{api_key}
```

```ini
api_endpoint=http://192.168.4.100:10801/kobo/98765432109876543210876543210987
```

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

### Create Stump Container via CLI

Source: https://www.stumpapp.dev/docs/getting-started/installation/docker

Commands to create the Stump container using Docker CLI, including options for standard volumes or bind mounts.

```bash
# replace my paths (left of colon) with your own
docker create \
  --name=stump \
  -e "PUID=1000" \
  -e "PGID=1000" \
  -p 10801:10801 \
  --volume "/home/aaronleopold/.stump:/config" \
  --volume "/media/books:/data" \
  --restart unless-stopped \
  aaronleopold/stump:latest
```

```bash
--mount type=volume,source=/home/aaronleopold/.stump,target=/config \
--mount type=volume,source=/media/books,target=/data \
```

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

### Monitor Container Logs

Source: https://www.stumpapp.dev/docs/getting-started/installation/docker

Command to follow the logs of the running Stump container.

```bash
docker logs -f stump
```

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

### Set Binary Permissions

Source: https://www.stumpapp.dev/docs/getting-started/installation/binaries

Command to grant execution permissions to the Stump server binary on macOS and Linux.

```bash
# Navigate to the folder containing the stump binary, e.g., ~/Stump
sudo chmod +x stump_server
```

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

### Add theme translation keys

Source: https://www.stumpapp.dev/docs/apps/web/themes

Include the new theme name in the locale JSON file to support UI localization.

```json
{
	"settingsScene": {
		"app/preferences": {
			"sections": {
				"themeSelect": {
					"options": {
						"system": "System",
						"light": "Light",
						"dark": "Dark",
						// ... other themes ...
						"midnight": "Midnight"
					}
				}
			}
		}
	}
}
```

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

### Configure KoReader sync server URL

Source: https://www.stumpapp.dev/docs/guides/integrations/koreader

The URL structure required for the custom sync server setting within the KoReader application.

```bash
http(s)://your-server({port})(/{baseUrl})/koreader/{api_key}
```

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

### List user accounts

Source: https://www.stumpapp.dev/docs/developer/cli/account

Displays a list of all user accounts, with an optional flag to filter by locked status.

```bash
./stump account list
```

```bash
./stump account list --locked true
```

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

### Configure theme behavior in useTheme hook

Source: https://www.stumpapp.dev/docs/apps/web/themes

Register the theme in the DARK_THEMES and THEMES_WITH_GRADIENTS arrays to enable specific UI behaviors.

```ts
export const DARK_THEMES = ['dark', 'ocean', 'cosmic', 'pumpkin', 'autumn', 'midnight']
```

```ts
export const THEMES_WITH_GRADIENTS = ['cosmic', 'midnight']
```

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

### Manage User Account Status via CLI

Source: https://www.stumpapp.dev/docs/guides/access-control/users

Commands to lock or unlock a user account using the Stump CLI.

```bash
./stump account unlock --username <username>
```

```bash
./stump account lock --username <username>
```

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

### Define a custom theme in CSS

Source: https://www.stumpapp.dev/docs/apps/web/themes

Add a new theme class to the themes.css file by defining required color variables.

```css
.midnight {
	/* MARK: backgrounds */
	--color-background: #000000;
	--color-background-inverse: #ffffff;

	/* ... other theme colors ... */
}
```

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

### Watch GraphQL changes

Source: https://www.stumpapp.dev/docs/developer/contributing

Execute this in the packages/graphql directory to automatically generate TypeScript types during development.

```bash
yarn graphql-codegen --watch
```

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

### Retrieve User and Group IDs

Source: https://www.stumpapp.dev/docs/getting-started/installation/docker

Use this command to determine the PUID and PGID values for your current user to ensure correct file permissions.

```bash
echo -e "PUID=$(id -u)\nPGID=$(id -g)"
```

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

### Unzip or Extract Stump Binaries

Source: https://www.stumpapp.dev/docs/getting-started/installation/binaries

Commands to extract the downloaded Stump archive on macOS and Linux systems.

```bash
# macOS
unzip ~/Downloads/stump-<version>-macos-arm.zip -d ~

# Linux
tar -xzf ~/Downloads/stump-<version>-linux-x64.tar.gz -C ~
```

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

### Migrate local account to OIDC

Source: https://www.stumpapp.dev/docs/developer/cli/account

Migrates data and permissions from a local account to an OIDC account. Both accounts must exist, and the OIDC account should be empty as it will be overwritten.

```bash
./stump account migrate-oidc --username <local-username> --oidc-email <oidc-email>
```

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

### Update Stump Container

Source: https://www.stumpapp.dev/docs/getting-started/installation/docker

Commands to pull the latest image and restart the container to apply updates.

```bash
docker compose pull stump
docker compose up -d
```

```bash
docker pull aaronleopold/stump:latest
docker restart stump
```

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

### Cron expression format

Source: https://www.stumpapp.dev/docs/guides/fundamentals/background-jobs

Visual representation of the 6-field cron expression format supported by Stump.

```bash
┌─────────── second
│ ┌───────── minute
│ │ ┌─────── hour
│ │ │ ┌───── day of month
│ │ │ │ ┌─── month
│ │ │ │ │ ┌─ day of week
│ │ │ │ │ │
* * * * * *
```

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

### Define @font-face in CSS

Source: https://www.stumpapp.dev/docs/apps/web/themes

Create a CSS file within the fonts directory to define the font family and source path.

```css
@font-face {
	font-family: 'My Font';
	/* define accordingly, this is an example */
	src: url('path/to/font.woff2') format('woff2');
}
```

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

### Bypass macOS App Signing Restrictions

Source: https://www.stumpapp.dev/docs/apps/desktop/security

Use this command to remove the quarantine attribute from the application bundle if macOS refuses to run the unsigned binary.

```bash
xattr -c /Applications/Stump.app
```
Tokens:
Raw