temple/Suwayomi-Server
1
0
Fork 0
mirror of https://github.com/Suwayomi/Suwayomi-Server.git synced 2026-06-30 09:24:34 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add Wiki to main repo to allow pull requests for improvements (#1647)

Browse Source
This commit is contained in:
Mitchell Syer
2025-09-15 09:25:13 -04:00
committed by GitHub
parent bbd7e30298
commit 1dd79a0b1e
7 changed files with 432 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
.github/workflows/wiki.yml vendored Normal file
View File

@@ -0,0 +1,41 @@
name: GitHub Wiki upload
on:
push:
branches:
- master
paths: [docs/**, .github/workflows/wiki.yml]
concurrency:
group: wiki
cancel-in-progress: true
permissions:
contents: write
jobs:
wiki:
name: Publish to GitHub Wiki
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
repository: ${{github.repository}}
path: ${{github.repository}}
- name: Checkout Wiki
uses: actions/checkout@v4
with:
repository: ${{github.repository}}.wiki
path: ${{github.repository}}.wiki
- name: Push to wiki
run: |
set -e
cd $GITHUB_WORKSPACE/${{github.repository}}.wiki
cp -r $GITHUB_WORKSPACE/${{github.repository}}/docs/* .
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add .
git diff-index --quiet HEAD || git commit -m "action: wiki sync" && git push

209
docs/Configuring-Suwayomi‐Server.md Normal file
View File

@@ -0,0 +1,209 @@
Suwayomi-Server configuration file is named `server.conf` and is located inside [the data directory](https://github.com/Suwayomi/Suwayomi-Server/wiki/The-Data-Directory).
The configuration file is written in HOCON. Google is your friend if you want to know more.
**Note:** new keys might be added in the future. Suwayomi generally attempts to update your conf file automatically, but some keys may need to be updated manually.
## Troubleshooting
### I messed up my configuration file
- The reference configuration file can be found [here](https://github.com/Suwayomi/Suwayomi-Server/blob/master/server/src/main/resources/server-reference.conf) replace your whole configuration or erroneous keys referring to it.
- Suwayomi will create a default configuration file when one doesn't exist, you can delete `server.conf` to get a copy of the reference configuration file after a restart.
### I am running Suwayomi in a headless environment (docker, NAS, VPS, etc.)
- Set `server.systemTrayEnabled` to false, it will prevent Suwayomi to attempt to create a System Tray icon.
- Set `server.initialOpenInBrowserEnabled`to false, it will prevent Suwayomi to attempt to open a browser on startup.
### My Suwayomi data directory/downloads size is getting to big
- Set `server.downloadsPath` to the desired path, if you only need to change where downloads are stored. You have to move/remove the existing downloads manually.
- Set the special `server.rootDir` key if you need Suwayomi to use a custom data directory path, refer to [this section](#overriding-tachidesk-servers-data-directory-path).
## Configuration Options
### Server ip and port bindings
```conf
server.ip = "0.0.0.0"
server.port = 4567
```
- `server.ip` can be a IP or domain name.
### Socks5 proxy
```
server.socksProxyEnabled = false
server.socksProxyHost = ""
server.socksProxyPort = ""
```
This section directs Suwayomi to connect to the network through a proxy server.
An example configuration can be:
```
server.socksProxyEnabled = true
server.socksProxyHost = "yourproxyhost.com"
server.socksProxyPort = "8080"
```
### webUI
```
server.webUIEnabled = true
server.initialOpenInBrowserEnabled = true
server.webUIInterface = "browser" # "browser" or "electron"
server.electronPath = ""
server.webUIFlavor = "WebUI" # "WebUI" or "Custom"
```
- `server.webUIEnabled` controls if Suwayomi will serve `Suwayomi-WebUI` and if it downloads/updates it on startup.
- `server.initialOpenInBrowserEnabled` controls if Suwayomi will attempt to open a brwoser/electron window on startup, disabling this on headless servers is recommended.
- `server.webUIInterface` which web interface Suwayomi should launch on startup, options are `"browser"` and `"electron"`
- `server.electronPath` path of the main electron executable, should be in double quotes
- `server.webUIFlavor` set `"WebUI"` to make the server download and update Suwayomi-WebUI automatically or `"Custom"` if you want the server to serve a custom web interface that you manage by yourself.
- Note: "Custom" would be useful if you want to test preview versions of Suwayomi-WebUI or when you are using or developing other web interfaces like the web version of Suwayomi-Sorayomi.
### Downloader
```
server.downloadAsCbz = true
server.downloadsPath = ""
server.autoDownloadNewChapters = false
server.excludeEntryWithUnreadChapters = true
server.autoDownloadNewChaptersLimit = 0
server.autoDownloadIgnoreReUploads = false
server.downloadConversions = {}
```
- `server.downloadAsCbz = true` configures Suwayomi to automatically compress chapters into CBZ.
- `server.downloadsPath = ""` the path where manga downloads will be stored, if the value is empty, the default directory `downloads` inside [the data directory](https://github.com/Suwayomi/Suwayomi-Server/wiki/The-Data-Directory) will be used. If you are on Windows the slashes `\` needs to be doubled(`\\`) or replaced with `/`
- `server.autoDownloadNewChapters = false` controls if Suwayomi should automatically download new chapters after a library update.
- `server.excludeEntryWithUnreadChapters = true` controls if Suwayomi will download new chapters for titles with unread chapters (requires `server.autoDownloadNewChapters`).
- `server.autoDownloadNewChaptersLimit = 0` sets how many chapters should be downloaded at most, `0` to disable the limit; if the limit is reached, new chapters will not be downloaded (requires `server.autoDownloadNewChapters`).
- `server.autoDownloadIgnoreReUploads = false` controls if Suwayomi will re-download re-uploads on update (requires `server.autoDownloadNewChapters`).
- `server.downloadConversions = {}` configures optional image conversions for all downloads. This is an [JSON object](https://en.wikipedia.org/wiki/JSON#Syntax), with the source image [mime type](https://en.wikipedia.org/wiki/Media_type) as the key and an object with the target mime type and options as value.
The following options are both valid:
```
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 source mime type `default` can be used as fallback to convert all images; a target mime type of `none` can be used to disable conversion for a particular format.
### Updater
```
server.excludeUnreadChapters = true
server.excludeNotStarted = true
server.excludeCompleted = true
server.globalUpdateInterval = 12
server.updateMangas = false
```
- `server.excludeUnreadChapters = true` controls if Suwayomi should include titles with unread chapters in the library update.
- `server.excludeNotStarted = true` controls if Suwayomi should include titles which weren't started yet in the library update.
- `server.excludeCompleted = true` controls if Suwayomi should include titles which are marked completed in the library update.
- `server.globalUpdateInterval = 12` sets the time in hours for the automatic library internal, `0` to disable it. Range: 6 <= n < ∞
- `server.updateMangas = false` controls if Suwayomi should also update title metadata along with fetching new chapters in the library update.
### Authentication
```
server.authMode = "none" # none, basic_auth or simple_login
server.authUsername = "user"
server.authPassword = "pass"
```
- `server.authMode = "none"`: Since v2.1.1867, Suwayomi supports two modes of authentication. Enabling authentication is useful when hosting on a public network/the Internet. If you used the original `server.basicAuth*` variables, it will be automatically migrated.
`basic_auth` configures Suwayomi for [Basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
`simple_login` works similarly to Basic Authentication, but presents a custom login page. The login is stored via a cookie and needs to be refreshed on every server restart or every 30 minutes.
- `server.authUsername` the username value that you have to provide when authenticating.
- `server.authPassword` the password value that you have to provide when authenticating.
**Note**: Basic access authentication sends username and password in cleartext and is not completely secure over HTTP, it's recommended to pair this feature with a reverse proxy server like nginx and expose the server over HTTPS. Similarly, with `simple_login`, the credentials are sent in cleartext on login, and the cookie is sent with every request. Also your browser caches the credentials/cookie, so you should be careful when accessing the server from non-private devices and use incognito mode.
### misc
```
server.debugLogsEnabled = false
server.systemTrayEnabled = true
server.maxLogFiles = 31
server.maxLogFileSize = "10mb"
server.maxLogFolderSize = "100mb"
server.extensionRepos = []
server.maxSourcesInParallel = 6
```
- `server.debugLogsEnabled` controls whether if Suwayomi-Server should print more information while being run inside a Terminal/CMD/Powershell window.
- `server.systemTrayEnabled = true` whether if Suwayomi-Server should show a System Tray Icon, disabling this on headless servers is recommended.
- `server.maxLogFiles = 31` sets the maximum number of days to keep files before they get deleted.
- `server.maxLogFileSize = "10mb"` sets the maximum size of a log file - values are formatted like: 1 (bytes), 1KB (kilobytes), 1MB (megabytes), 1GB (gigabytes)
- `server.maxLogFolderSize = "100mb"` sets the maximum size of all saved log files - values are formatted like: 1 (bytes), 1KB (kilobytes), 1MB (megabytes), 1GB (gigabytes)
- `server.extensionRepos` is a list of extension repositories for custom sources. Uses the same format as Mihon; each entry is expected to be a string URL pointing to a JSON file representing the repository.
- `server.maxSourcesInParallel = 6` sets how many sources can do requests (updates, downloads) in parallel. Updates/downloads are grouped by source and all mangas of a source are updated/downloaded synchronously. Range: 1 <= n <= 20.
### Backup
```
server.backupPath = ""
server.backupTime = "00:00"
server.backupInterval = 1
server.backupTTL = 14
```
- `server.backupPath = ""` the path where backups will be stored, if the value is empty, the default directory `backups` inside [the data directory](https://github.com/Suwayomi/Suwayomi-Server/wiki/The-Data-Directory) will be used. If you are on Windows the slashes `\` needs to be doubled(`\\`) or replaced with `/`
- `server.backupTime = "00:00"` sets the time of day at which the automated backup should be triggered.
- `server.backupInterval = 1` sets the interval in which the server will automatically create a backup in days, `0` to disable it.
- `server.backupTTL = 14` sets how long backup files will be kept before they will get deleted in days, `0` to disable it.
### Local Source
```
server.localSourcePath = ""
```
- `server.localSourcePath = ""` the path from where local manga are loaded, if the value is empty, the default directory `local` inside [the data directory](https://github.com/Suwayomi/Suwayomi-Server/wiki/The-Data-Directory) will be used. If you are on Windows the slashes `\` needs to be doubled(`\\`) or replaced with `/`
### Cloudflare bypass
```
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
```
- `server.flareSolverrEnabled = false` controls if Suwayomi attempts to connect to FlareSolverr if a CloudFlare challenge is detected.
- `server.flareSolverrUrl = "http://localhost:8191"` sets the address where Suwayomi attempts to connect to FlareSolverr. The instance needs to run and be accessible from the server where Suwayomi is running for CloudFlare bypass to work.
- `server.flareSolverrTimeout = 60` sets the timeout to wait for FlareSolverr to solve a given challenge in seconds.
- `server.flareSolverrSessionName = "suwayomi"` sets the session name that FlareSolverr should use. Tells FlareSolverr which set of cookies to use.
- `server.flareSolverrSessionTtl = 15` sets the time for how long sessions in FlareSolverr should live in minutes. After this time, FlareSolverr will forget cookies.
- `server.flareSolverrAsResponseFallback = false` allows Suwayomi to use the contents of the request that FlareSolverr received in case Suwayomi sees a CloudFlare challenge but FlareSolverr does not (which prevents it from solving the challenge).
**Note:** Byparr is a popular alternative to FlareSolverr. It uses the same API schema as FlareSolverr, so you can also configure the address of a Byparr instance in `server.flareSolverrUrl`.
### OPDS
```
server.opdsUseBinaryFileSizes = false
server.opdsItemsPerPage = 50
server.opdsEnablePageReadProgress = true
server.opdsMarkAsReadOnDownload = false
server.opdsShowOnlyUnreadChapters = false
server.opdsShowOnlyDownloadedChapters = false
server.opdsChapterSortOrder = "DESC"
```
- `server.opdsUseBinaryFileSizes = false` controls if Suwayomi should display file sizes in binary units (KiB, MiB, GiB) or decimal (KB, MB, GB) in OPDS listings.
- `server.opdsItemsPerPage = 50` sets the number of items per page in OPDS listings. Range: 10 <= n <= 5000.
- `server.opdsEnablePageReadProgress = true` controls if Suwayomi should include information to track chapter read progress in OPDS chapter page listings. This will cause the reader to mark the pages as read when it downloads the images.
- `server.opdsMarkAsReadOnDownload = false` controls if Suwayomi should mark the chapters as read when it is downloaded through the OPDS listing.
- `server.opdsShowOnlyUnreadChapters = false` controls if OPDS listings should only include unread chapters.
- `server.opdsShowOnlyDownloadedChapters = false` controls if OPDS listings should only include downloaded chapters.
- `server.opdsChapterSortOrder = "DESC"` sets the default chapter sort order in OPDS listings, either `"ASC"` or `"DESC"`
## Overriding configuration options with command-line arguments
You can override the above configuration options with command-line arguments.
You usually only need to set this when using custom setups like a portable version of Suwayomi or your if your User dir cannot be written to or your system administrator doesn't allow it.
Use the pattern bellow.
```
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>
```
for example to force launching Suwayomi-Server in electron you would have something like:
```
java -Dsuwayomi.tachidesk.config.server.webUIInterface=electron -Dsuwayomi.tachidesk.config.server.electronPath="/path/to/electron" -jar Suwayomi-Server-v0.X.Y-rXXXX.jar
```
**Note:** you can put the command above in a custom launcher script like the ones found [here](https://github.com/Suwayomi/Suwayomi-Server/tree/master/scripts/resources).
## Overriding Suwayomi-Server's Data Directory path
The only possible way to override the default Data Directory path is with command-line arguments(the chicken and egg problem!).
Add the special config option `server.rootDir="<path to data directory>"` to your command-line arguments.
For example:
```
java -Dsuwayomi.tachidesk.config.server.rootDir="/path/to/data/directory" -jar Suwayomi-Server-v0.X.Y-rXXXX.jar
```

8
docs/Getting-Extensions.md Normal file
View File

@@ -0,0 +1,8 @@
1. **Install the latest version(or preview):** https://github.com/Suwayomi/Suwayomi-Server/releases/latest
2. Find an extensions repo, there is now no default extensions and you have to use google to find a Tachiyomi extension repo.
- Note: The repo should look like `https://raw.githubusercontent.com/user/reponame` or `https://www.github.com/user/reponame`
3. Configure it using one of the following:
- Suwayomi-Server option 1: With the **new launcher**, go to the `Extensions` tab and add the extensions repo.
- Suwayomi-Server option 2: Use the **server settings** in **WebUI** to add the extensions repo.
- Suwayomi-Server option 3: Go to the `server.conf` file in the data files and add the extensions repo.
- Suwayomi docker container: Edit the `EXTENSION_REPOS` environment variable and add the extension repo in the format listed in the container README.

3
docs/Home.md Normal file
View File

@@ -0,0 +1,3 @@
Welcome to the Suwayomi wiki!
Look at the pages section for links and stuff.

135
docs/Local-Source.md Normal file
View File

@@ -0,0 +1,135 @@
Follow the steps below to create local manga.
1. Place correctly structured manga inside the `local` directory located in [Suwayomi's data directory](https://github.com/Suwayomi/Suwayomi-Server/wiki/The-Data-Directory).
1. You can then access the manga in the **Local source** source.
If you add more chapters then you'll have to manually refresh the chapter list.
Supported chapter formats are folder with pictures inside (such as `.jpg`, `.png`, etc), `ZIP`/`CBZ`, `RAR`/`CBR` and `EPUB`. But expect better performance with directories and `ZIP`/`CBZ`.
**Note:** While Suwayomi does support chapters compressed as **RAR** or **CBR**, note that **RAR** or **CBR** files using the **RAR5** format are not supported yet.
**Note:** If **CBR** or **RAR** files do not work, you may need to extract and re-compress them into one of the supported formats.
## Folder Structure
Suwayomi requires a specific folder structure for local manga to be correctly processed. Local manga will be read from the `local` folder. Each manga must have a `Manga` folder and a `Chapter` folder. Images will then go into the chapter folder. See below for more information on archive files. You can refer to the following example:
<div class="side-by-side">
<ul class="file-tree">
<li>
local/
<ul>
<li>
<span class="ft-icon ft-folder">Manga title/</span>
<ul>
<li>
<span class="ft-icon ft-folder">Chapter 01 - Prologue/</span>
<ul>
<li><span class="ft-icon ft-image">page01.png</span></li>
<li><span class="ft-icon ft-image">page02.png</span></li>
<li><span class="ft-icon ft-image">page03.png</span></li>
<li><span class="ft-icon ft-image">...</span></li>
</ul>
</li>
<li>
<span class="ft-icon ft-folder">Chapter 02 - A hero's journey/</span>
<ul>
<li><span class="ft-icon ft-image">01.jpg</span></li>
<li><span class="ft-icon ft-image">02.jpg</span></li>
<li><span class="ft-icon ft-image">03.jpg</span></li>
<li><span class="ft-icon ft-image">...</span></li>
</ul>
</li>
<li><span class="ft-icon ft-image">cover.jpg</span></li>
</ul>
</li>
<li>
<span class="ft-icon ft-folder">Other Manga title/</span>
<ul>
<li><span class="ft-icon ft-image">cover.jpg</span></li>
<li>
<span class="ft-icon ft-folder">ch001/</span>
<ul>
<li><span class="ft-icon ft-image">01 - cover.jpg</span></li>
<li><span class="ft-icon ft-image">02 - first page.jpeg</span></li>
<li><span class="ft-icon ft-image">03 - second.jpg</span></li>
<li><span class="ft-icon ft-image">...</span></li>
</ul>
</li>
<li>
<span class="ft-icon ft-folder">ch002/</span>
<ul>
<li><span class="ft-icon ft-image">001.jpg</span></li>
<li><span class="ft-icon ft-image">002.jpg</span></li>
<li><span class="ft-icon ft-image">003.jpg</span></li>
<li><span class="ft-icon ft-image">...</span></li>
</ul>
</li>
</ul>
</li>
<li>...</li>
</ul>
</li>
</ul>
</div>
**Note:** Chapter and page names should be ordered alphanumerically, using zero padded name prefixes is usually the best option.
The path to the folder with images must contain both the manga title and the chapter name (as seen above).
## Archive Files
Archive files such as `ZIP`/`CBZ` are supported but the folder structure inside is not. Any folders inside the archive file are ignored. You must place the archive inside the `Manga` folder where the name will become the `Chapter` title. All images inside the archive regardless of folder structure will become pages for that chapter.
<ul class="file-tree">
<li>
local/
<ul>
<li>
<span class="ft-icon ft-folder">Manga title/</span>
<ul>
<li>
<span class="ft-icon ft-zip">ch1.zip</span>
</li>
<li>
<span class="ft-icon ft-zip">ch2.zip</span>
</li>
<span class="ft-icon ft-image">cover.jpg</span>
</ul>
</li>
<li>...</li>
</ul>
</li>
</ul>
## Advanced
### Editing local manga details
It is possible to add details to local manga. Like manga from other catalogs, you add information about the manga such as the author, artist, description, and genre tags.
To import details along with your local manga, you have to create a json file. It can be named anything but it must be placed within the **Manga** folder. A standard file name is `details.json`. This file will contain the extended details about the manga in the `JSON` format. You can see the example below on how to build the file. Once the file is there, the app should load the data when you first open the manga or you can pull down to refresh the details.
You can copy the following example and edit the details as needed:
``` 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"]
}
```
### Using a custom cover image
It is also possible to use a custom image as a cover for each local manga.
To do this, you only need to place the image file, that needs to be named
`cover.jpg`, in the root of the manga folder. The app will then use your
custom image in the local source listing.

17
docs/The-Data-Directory.md Normal file
View File

@@ -0,0 +1,17 @@
## Default data directory
The default data directory is located below depending on your operating system:
Replace `<Account>` with your account/username.
On Windows 7 and later : `C:\Users\<Account>\AppData\Local\Tachidesk`
On Windows XP : `C:\Documents and Settings\<Account>\Application Data\Local Settings\Tachidesk`
On Mac OS X : `/Users/<Account>/Library/Application Support/Tachidesk`
On Unix/Linux : `/home/<account>/.local/share/Tachidesk`
## Custom
You can set Suwayomi-Server to use a specific directory with the `-Dsuwayomi.tachidesk.config.server.rootDir` startup argument.
An example of this is `java -Dsuwayomi.tachidesk.config.server.rootDir="D:\Tachidesk Data" -jar Tachidesk-vX.Y.Z-rxxxx.jar`

19
docs/Troubleshooting.md Normal file
View File

@@ -0,0 +1,19 @@
## General Troubleshooting
This guide will try to fix Suwayomi by reseting it to a clean install state.
- Make sure you have a recent backup of your library or create one in the app (if possible) because we **are going to wipe all Suwayomi data**.
- Make sure Suwayomi is not running (right click on tray icon and quit or kill it through the way your Operating System provides)
- Clear all browsing data on your browser if you use Suwayomi from a browser.
- Delete the Suwayomi data directory located below and re-run the app.
Note: Replace `<Account>` with the currently logged in account/username on your pc.
On Mac OS X : `/Users/<Account>/Library/Application Support/Tachidesk`
On Windows XP : `C:\Documents and Settings\<Account>\Application Data\Local Settings\Tachidesk`
On Windows 7 and later : `C:\Users\<Account>\AppData\Local\Tachidesk`
On Unix/Linux : `/home/<account>/.local/share/Tachidesk`
- In the case that you have to periodically perform this fix or the problem persists or the method failed to fix it, open an issue or Join the [Suwayomi discord server](https://discord.gg/DDZdqZWaHA) to hang out with the community and to receive support and help.