Suwayomi Server

https://github.com/suwayomi/suwayomi-server
Admin
Suwayomi Server is a free, open-source, multi-platform manga reader server compatible with Mihon...
Tokens:12,436
Snippets:181
Trust Score:7
License:MPL-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Suwayomi Server from MPR

Source: https://github.com/suwayomi/suwayomi-server/blob/master/README.md

Clone the repository and use `makedeb` to install the server package. This method is outdated.

```bash
git clone https://mpr.makedeb.org/tachidesk-server.git
cd tachidesk-server
makedeb -si
```

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

### Add Suwayomi Server PPA and Install

Source: https://github.com/suwayomi/suwayomi-server/blob/master/README.md

Add the official Suwayomi PPA to your system and install the server package. This method is outdated.

```bash
sudo add-apt-repository ppa:suwayomi/tachidesk-server
sudo apt update
sudo apt install tachidesk-server
```

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

### Force Electron interface via command-line

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Example command to launch the server using the Electron interface.

```bash
java -Dsuwayomi.tachidesk.config.server.webUIInterface=electron -Dsuwayomi.tachidesk.config.server.electronPath="/path/to/electron" -jar Suwayomi-Server-v0.X.Y-rXXXX.jar
```

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

### Install Suwayomi Server via AUR

Source: https://github.com/suwayomi/suwayomi-server/blob/master/README.md

Use `yay` to install the binary package from the Arch User Repository.

```bash
yay -S suwayomi-server-bin
```

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

### Run Server in Development Mode

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

Execute this command to start the Suwayomi-Server in development mode, including detailed stack traces for debugging.

```bash
./gradlew :server:run --stacktrace
```

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

### Example Conversion Request

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Demonstrates the structure of a POST request sent by the server to a conversion URL.

```bash
curl -X POST "http://localhost:9999/convert" -F "image=@cat.png;type=image/png"
```

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

### Set Custom Data Directory with Startup Argument

Source: https://github.com/suwayomi/suwayomi-server/wiki/The-Data-Directory

Use the `-Dsuwayomi.tachidesk.config.server.rootDir` argument when starting the Suwayomi-Server JAR to specify a custom data directory. This is useful for managing data in a specific location.

```bash
java -Dsuwayomi.tachidesk.config.server.rootDir="D:\Tachidesk Data" -jar Tachidesk-vX.Y.Z-rxxxx.jar
```

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

### Run Suwayomi Server JAR Release

Source: https://github.com/suwayomi/suwayomi-server/blob/master/README.md

Execute the Suwayomi Server JAR file using Java. Ensure JRE 21 or newer is installed. This will open a browser window.

```bash
java -jar Suwayomi-Server-vX.Y.Z-rxxxx.jar
```

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

### Build Windows Package

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

After building the server JAR, navigate to the `scripts` directory and execute this command to create a Windows distributable zip package. Specify `win32` or `win64` for the target architecture. The output zip will be in `server/build/`.

```bash
./windows-bundler.sh win32
```

```bash
./windows-bundler.sh win64
```

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

### Build Full Suwayomi-Server Jar

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

Use this command to build a bundled JAR containing both the server and the web UI. The output jar will be located in `server/build/`.

```bash
./gradlew server:downloadWebUI server:shadowJar
```

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

### Configure Miscellaneous Server Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Controls logging behavior and system tray integration.

```text
server.debugLogsEnabled = false
server.systemTrayEnabled = true
server.maxLogFiles = 31
server.maxLogFileSize = "10mb"
server.maxLogFolderSize = "100mb"
```

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

### Configure Extension and Source Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Manages extension repositories and parallel request limits for sources.

```text
server.extensionStores = []
server.maxSourcesInParallel = 6
```

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

### GraphiQL Initialization Script

Source: https://github.com/suwayomi/suwayomi-server/blob/master/server/src/main/resources/graphql-playground.html

JavaScript code to initialize the GraphiQL React application, configure the fetcher, and mount it to the DOM.

```javascript
import React from 'react'; import ReactDOM from 'react-dom/client'; import { GraphiQL, HISTORY_PLUGIN } from 'graphiql'; import { createGraphiQLFetcher } from '@graphiql/toolkit'; import { explorerPlugin } from '@graphiql/plugin-explorer'; import 'graphiql/setup-workers/esm.sh'; const fetcher = createGraphiQLFetcher({ url: window.location.href, subscriptionUrl: window.location.href.replace(/^http/,'ws') }); const plugins = [HISTORY_PLUGIN, explorerPlugin()]; function App() { return React.createElement(GraphiQL, { fetcher, plugins, defaultEditorToolsVisibility: true, }); } const container = document.getElementById('graphiql'); const root = ReactDOM.createRoot(container); root.render(React.createElement(App));
```

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

### Configure Server IP and Port

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Sets the network interface and port for the server to listen on.

```conf
server.ip = "0.0.0.0"
server.port = 4567
```

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

### Run All Tests

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

This command executes all tests within the Suwayomi-Server project.

```bash
./gradlew :server:test
```

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

### Override configuration via command-line arguments

Source: https://github.com/suwayomi/suwayomi-server/blob/master/docs/Configuring-Suwayomi‐Server.md

Use the -Dsuwayomi.tachidesk.config prefix to pass configuration options to the server jar.

```bash
java -Dsuwayomi.tachidesk.config.<configuration option 1>=<configuration value 1> -Dsuwayomi.tachidesk.config.<configuration option 2>=<configuration value 2> ... -Dsuwayomi.tachidesk.config.<configuration option N>=<configuration value N> -jar <path to server jar>
```

```bash
java -Dsuwayomi.tachidesk.config.server.webUIInterface=electron -Dsuwayomi.tachidesk.config.server.electronPath="/path/to/electron" -jar Suwayomi-Server-v0.X.Y-rXXXX.jar
```

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

### Build Server-Only Jar

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

To build a JAR containing only the server component, first ensure the `WebUI.zip` is removed from the resources, then run this command. The output jar will be located in `server/build/`.

```bash
./gradlew server:shadowJar
```

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

### Enable Suwayomi Server NixOS Module

Source: https://github.com/suwayomi/suwayomi-server/blob/master/README.md

Configure your NixOS system to enable the Suwayomi Server service by adding this to your configuration.nix.

```nix
{
  services.suwayomi-server = {
    enable = true;
  };
}
```

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

### Configure Database Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Settings for defining the database type and connection parameters for Suwayomi Server.

```properties
server.databaseType = H2 # H2, POSTGRESQL
server.databaseUrl = "postgresql://localhost:5432/suwayomi"
server.databaseUsername = ""
server.databasePassword = ""
server.useHikariConnectionPool = true
```

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

### Configure SyncYomi Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Settings for enabling and configuring the SyncYomi synchronization service.

```properties
server.syncYomiEnabled = false
server.syncYomiHost = ""
server.syncYomiApiKey = ""
server.syncDataManga = true
server.syncDataChapters = true
server.syncDataTracking = true
server.syncDataHistory = true
server.syncDataCategories = true
server.syncInterval = "0s"
```

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

### Override configuration via command-line arguments

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

General pattern for passing multiple configuration overrides to the server jar.

```bash
java -Dsuwayomi.tachidesk.config.<configuration option 1>=<configuration value 1> -Dsuwayomi.tachidesk.config.<configuration option 2>=<configuration value 2> ... -Dsuwayomi.tachidesk.config.<configuration option N>=<configuration value N> -jar <path to server jar>
```

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

### Configure KOReader Sync Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Configuration for connecting Suwayomi to a KOReader sync server, including authentication and conflict resolution strategies.

```properties
server.koreaderSyncServerUrl = "https://sync.koreader.rocks/"
server.koreaderSyncUsername = ""
server.koreaderSyncUserkey = ""
server.koreaderSyncDeviceId = ""
server.koreaderSyncChecksumMethod = BINARY # BINARY or FILENAME
server.koreaderSyncPercentageTolerance = 1.0E-15 # range: [1.0E-15, 1.0]
server.koreaderSyncStrategyForward = PROMPT # PROMPT, KEEP_LOCAL, KEEP_REMOTE, DISABLED
server.koreaderSyncStrategyBackward = DISABLED # PROMPT, KEEP_LOCAL, KEEP_REMOTE, DISABLED
```

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

### Configure Download Conversions

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Sets up image conversion rules for downloads, supporting both local mime-type conversion and external URL-based processing.

```text
server.downloadConversions = { "image/webp" : { target : "image/jpeg", compressionLevel = 0.8 }}
# -- or --
server.downloadConversions."image/webp" = {
  target = "image/jpeg"   # image type to convert to
  compressionLevel = 0.8  # quality in range [0,1], leave away to use default compression
}
# -- a url example --
server.downloadConversions = { "default" : { target : "http://localhost:9999/convert" }}
# -- a url with all parameters example --
server.downloadConversions = { 
    "default" : {
        target : "http://localhost:9999/convert",
        callTimeout : 10m,
        connectTimeout : 10s,
        headers : { 
            "authorization" : "MyPassword"
        }
    }
}
```

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

### Build Android JAR Maven Repository

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

Run this script from the project's root directory to download and rebuild the Android JAR from Google's repository. This is necessary for creating a local Maven repository for the `android-jar` branch.

```bash
AndroidCompat/getAndroid.sh
```

```powershell
AndroidCompat/getAndroid.ps1
```

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

### Configure Backup Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Defines the automated backup schedule, storage path, and data inclusion preferences for the server.

```text
server.backupPath = ""
server.backupTime = "00:00"
server.backupInterval = 1
server.backupTTL = 14
server.autoBackupIncludeManga = true
server.autoBackupIncludeCategories = true
server.autoBackupIncludeChapters = true
server.autoBackupIncludeTracking = true
server.autoBackupIncludeHistory = true
server.autoBackupIncludeClientData = true
server.autoBackupIncludeServerSettings = true
```

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

### Configure Web UI Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Controls the behavior, interface, and update channels for the Suwayomi Web UI.

```conf
server.webUIEnabled = true
server.initialOpenInBrowserEnabled = true
server.webUIInterface = "browser" # "browser" or "electron"
server.electronPath = ""
server.webUIFlavor = "WebUI" # "WebUI" or "Custom"
server.webUIChannel = preview # "BUNDLED" or "STABLE" or "PREVIEW"
server.webUIUpdateCheckInterval = 23
server.webUISubpath = ""
```

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

### Configure Local Source Path

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Sets the directory path from which local manga files are loaded by the server.

```text
server.localSourcePath = ""
```

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

### Configure Downloader Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Defines global download behavior, including storage paths, automatic chapter downloads, and CBZ compression.

```text
server.downloadAsCbz = true
server.downloadsPath = ""
server.autoDownloadNewChapters = false
server.excludeEntryWithUnreadChapters = true
server.autoDownloadNewChaptersLimit = 0
server.autoDownloadIgnoreReUploads = false
server.downloadConversions = {}
```

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

### Configure WebView Provider

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Enables or disables the KCEF WebView provider.

```conf
server.kcefEnabled = true
```

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

### Import Maps Configuration

Source: https://github.com/suwayomi/suwayomi-server/blob/master/server/src/main/resources/graphql-playground.html

JSON configuration defining module imports and subresource integrity hashes for GraphiQL and its dependencies.

```json
{ "imports": { "react": "https://esm.sh/react@19.2.8", "react/": "https://esm.sh/react@19.2.8/", "react-dom": "https://esm.sh/react-dom@19.2.8", "react-dom/": "https://esm.sh/react-dom@19.2.8/", "graphiql": "https://esm.sh/graphiql@5.2.4?standalone&external=react,react-dom,@graphiql/react,graphql", "graphiql/": "https://esm.sh/graphiql@5.2.4/", "@graphiql/plugin-explorer": "https://esm.sh/@graphiql/plugin-explorer@5.1.3?standalone&external=react,@graphiql/react,graphql", "@graphiql/react": "https://esm.sh/@graphiql/react@0.37.7?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid", "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit@0.12.1?standalone&external=graphql", "graphql": "https://esm.sh/graphql@17.0.2", "@emotion/is-prop-valid": "data:text/javascript," }, "integrity": { "https://esm.sh/react@19.2.8": "sha384-ZLbEMZxxxJSWKr0slZZsXGR6UNzfnEk4+qYI9PLH9QSxvWWQjs3UgkzrGuo33roA", "https://esm.sh/react-dom@19.2.8": "sha384-jssD0f2tUCDrNPAwM/2fFwybg7wF0K+9oVfFE0a7r0n7wb2UVP4/uYyWIZKGxG6L", "https://esm.sh/graphiql@5.2.4": "sha384-3feoWeu5QZYyfhHQyP8i+VBW+tYf58tTwgBb8Fsrw2QlP/YRBR2tscNGcYyRDtHC", "https://esm.sh/graphiql@5.2.4?standalone&external=react,react-dom,@graphiql/react,graphql": "sha384-n1sWmquV8wXH/vbn5Q8BaQAw8iAFku5zAs2fPBrht0L/OP4/qgZWL/v/WhMLFPBH", "https://esm.sh/@graphiql/plugin-explorer@5.1.3": "sha384-aDt72jaNBi2he5K4f47qh+xnS6Za54L6vuoNt6KtToLAJfebp23zCaAl3zXGl7dV", "https://esm.sh/@graphiql/react@0.37.7?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid": "sha384-U8awo9eG6M8scx4fjis/pNfYja4d5EtxOFYcmvDGG8K4Rt/bGB6Km1hxbQXZr9qH", "https://esm.sh/@graphiql/toolkit@0.12.1?standalone&external=graphql": "sha384-+cNTwZgIW33q7A4E+ZoCMqzcXdfVIc2VthQvJ0uDpRXERBWYuDKPVMzvdQU8x48o", "https://esm.sh/graphql@17.0.2": "sha384-IPvlcmnvWT91sKqwbg9MxPXJUuPmSdwXCp22x6hcbBkAEhlfSKkMLR3v19K9iRUp" } }
```

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

### Run Specific Test Class

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

To run tests for a particular class, use this command, replacing `<package.with.classname>` with the fully qualified name of the test class.

```bash
./gradlew :server:test --tests <package.with.classname>
```

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

### Configure Authentication Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Defines authentication modes and JWT parameters for securing the server.

```text
server.authMode = "none" # none, basic_auth, simple_login or ui_login
server.authUsername = "user"
server.authPassword = "pass"
server.jwtAudience = "suwayomi-server-api"
server.jwtTokenExpiry = "5m"
server.jwtRefreshExpiry = "60d"
```

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

### GraphQL API

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

The Suwayomi Server exposes a GraphQL API that can be accessed via POST requests to the /api/graphql endpoint. A GraphiQL IDE is also available at the same endpoint for interactive querying and API exploration.

```APIDOC
## GraphQL API

### Description
The GraphQL API allows clients to query data and perform actions on the Suwayomi Server. It supports POST requests for queries and mutations.

### Endpoint
`/api/graphql`

### Usage
Send POST requests with your GraphQL query or mutation to this endpoint. The GraphiQL IDE is available at the same URL for interactive use.
```

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

### GraphiQL CSS Styles

Source: https://github.com/suwayomi/suwayomi-server/blob/master/server/src/main/resources/graphql-playground.html

Basic CSS styles to ensure the GraphiQL container occupies the full viewport height and centers the loading indicator.

```css
GraphiQL body { margin: 0; } #graphiql { height: 100dvh; } .loading { height: 100%; display: flex; align-items: center; justify-content: center; font-size: 4rem; }
```

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

### Configure Updater Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Manages library update behavior, including filtering criteria and update frequency.

```text
server.excludeUnreadChapters = true
server.excludeNotStarted = true
server.excludeCompleted = true
server.globalUpdateInterval = 12
server.updateMangas = false
```

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

### Override data directory path

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Command to specify a custom root directory for server data.

```bash
java -Dsuwayomi.tachidesk.config.server.rootDir="/path/to/data/directory" -jar Suwayomi-Server-v0.X.Y-rXXXX.jar
```

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

### Query SQLite Version Programmatically

Source: https://github.com/suwayomi/suwayomi-server/blob/master/AndroidCompat/src/main/java/android/database/sqlite/package.html

Use this code to query the SQLite version by creating and querying an in-memory database. Ensure the Cursor is properly handled.

```Java
String query = "select sqlite_version() AS sqlite_version";
SQLiteDatabase db = SQLiteDatabase.openOrCreateDatabase(":memory:", null);
Cursor cursor = db.rawQuery(query, null);
String sqliteVersion = "";
if (cursor.moveToNext()) {
    sqliteVersion = cursor.getString(0);
}
```

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

### REST API (Deprecated)

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

The Suwayomi Server also provides a REST API at /api/v1, which is planned for deprecation. An interactive Swagger UI is available at /api/swagger-ui for exploring the REST endpoints.

```APIDOC
## REST API (Deprecated)

### Description
The REST API provides access to server functionalities. It is marked for deprecation and will be removed in future versions. An interactive Swagger UI is available for exploration.

### Endpoint
`/api/v1`

### Swagger UI
`/api/swagger-ui`

### Warning
This API is soon to be deprecated.
```

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

### Configure SOCKS5 Proxy

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Settings for routing network traffic through a SOCKS5 proxy.

```conf
server.socksProxyEnabled = false
server.socksProxyVersion = 5 # 4 or 5
server.socksProxyHost = ""
server.socksProxyPort = ""
server.socksProxyUsername = ""
server.socksProxyPassword = ""
```

```conf
server.socksProxyEnabled = true
server.socksProxyHost = "yourproxyhost.com"
server.socksProxyPort = "8080"
```

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

### Tracker Client Authorization (OAuth)

Source: https://github.com/suwayomi/suwayomi-server/blob/master/CONTRIBUTING.md

This section details the OAuth flow for authorizing tracker clients with Suwayomi Server, emphasizing the use of a `state` object with a `redirectUrl` for handling authentication results.

```APIDOC
## Tracker Client Authorization (OAuth)

### Description
This flow enables tracker clients to authorize with Suwayomi Server using OAuth. Due to the dynamic nature of Suwayomi Server URLs, a specific redirection mechanism is employed.

### Preconditions for Redirection
When initiating the OAuth process, the `state` object must be included in the authorization URL. This object must contain:
- `redirectUrl`: The client route where the authentication result will be handled.
- Any other required information, such as the tracker client's server `id`.

### Example Authorization URL (AniList)
```
https://anilist.co/api/v2/oauth/authorize?client_id=ID&response_type=token&state={ redirectUrl: "http://localhost:4567/handle/oauth/result", trackerId: 1, anyOtherInfo: "your client requires" }
```

### Handling Authentication Result
After permission is granted, the user is redirected to the `redirectUrl` specified in the `state` object. The response will include an `access_token` and other relevant details.

### Example Redirect URL (AniList - Decoded)
```
http://localhost:4567/handle/oauth/result?access_token=TOKEN&token_type=Bearer&expires_in=31622400&state={ redirectUrl: "http://localhost:4567/handle/oauth/result", trackerId: 1, anyOtherInfo: "your client requires" }
```

### Finalizing Login
Pass the complete redirect URL (containing the access token and state) to the Suwayomi Server as the `callbackUrl` to finalize the login process.
```

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

### Local Manga Details JSON Structure

Source: https://github.com/suwayomi/suwayomi-server/wiki/Local-Source

Use this JSON structure to add metadata like title, author, artist, description, and genre tags to local manga. Place this file as 'details.json' in the manga's root folder. The 'status' field uses numerical codes.

```json
{
	"title": "Example Title",
	"author": "Example Author",
	"artist": "Example Artist",
	"description": "Example Description",
	"genre": ["genre 1", "genre 2", "etc"],
	"status": "0",
	"_status values": ["0 = Unknown", "1 = Ongoing", "2 = Completed", "3 = Licensed"]
}
```

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

### Configure Cloudflare Bypass via FlareSolverr

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Configures the connection to a FlareSolverr instance to handle Cloudflare challenges.

```text
server.flareSolverrEnabled = false
server.flareSolverrUrl = "http://localhost:8191"
server.flareSolverrTimeout = 60 # time in seconds
server.flareSolverrSessionName = "suwayomi"
server.flareSolverrSessionTtl = 15 # time in minutes
server.flareSolverrAsResponseFallback = false
```

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

### Configure OPDS Server Settings

Source: https://github.com/suwayomi/suwayomi-server/wiki/Configuring-Suwayomi‐Server

Settings for customizing OPDS feed behavior, including sorting, filtering, and mimetype options.

```properties
server.opdsUseBinaryFileSizes = false
server.opdsItemsPerPage = 50
server.opdsEnablePageReadProgress = true
server.opdsMarkAsReadOnDownload = false
server.opdsShowOnlyUnreadChapters = false
server.opdsShowOnlyDownloadedChapters = false
server.opdsChapterSortOrder = "DESC"
server.opdsCbzMimetype = "MODERN"
server.opdsSkipChapterMetadataFeed = false
```
Tokens:
Raw