Applications AWS

Suwayomi Server on AWS User Guide

| Product: Suwayomi Server on AWS

Overview

This image runs Suwayomi Server, a free and open source, self hosted manga server and reader. Suwayomi is compatible with Tachiyomi extension sources: you install extensions, browse and search catalogs, and read or download manga from a clean browser reading UI, with your library kept on your own instance.

Suwayomi Server is installed as a single self contained jar under /opt/suwayomi, run by a dedicated unprivileged suwayomi system account under a systemd service that starts it on boot and restarts it on failure. The server runs on a headless OpenJDK 21 runtime and binds only to the loopback interface on port 4567. Its data root is /var/lib/suwayomi, a dedicated, independently resizable EBS data volume that holds the manga library database, downloaded chapters, thumbnails, installed extension sources, the bundled web UI assets and the server configuration.

The web reading UI is served on port 80 by an nginx reverse proxy in front of Suwayomi. Because Suwayomi ships with no authentication of its own, which would leave the reader open to anyone who can reach it, this image is secure by default: nginx enforces HTTP Basic authentication on every request except a dedicated anonymous health endpoint at /healthz. The administrator password is generated on the first boot of every deployed instance, so two instances launched from the same AMI never share a password. It is written to /root/suwayomi-credentials.txt with mode 0600 so that only the root user can read it.

Suwayomi library view

Prerequisites

Before you deploy this image you need:

  • An Amazon Web Services account where you can launch EC2 instances
  • IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
  • An EC2 key pair in the target Region for SSH access to the instance
  • A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the web UI from the networks you will read from
  • The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Suwayomi Server. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger (Suwayomi is a JVM workload; size it for your library and reading concurrency). Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web UI. Leave the root volume at the default size or larger, and keep the attached data volume that holds your library.

Select Launch instance. First boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Suwayomi Server Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=suwayomi}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

OS variant SSH login user
Ubuntu 24.04 ubuntu 
ssh -i /path/to/your-key.pem ubuntu@<public-ip>

Step 4: Retrieve the Administrator Password

The reader is protected by HTTP Basic authentication. A unique administrator password is generated on first boot and stored in a root only file. Retrieve it over SSH:

sudo cat /root/suwayomi-credentials.txt

The file lists the reader URL, the user name (admin) and the generated password. Keep it safe; it is unique to this instance.

Step 5: Confirm the Services Are Running

Confirm that both the Suwayomi server and the nginx reverse proxy are active, and that the anonymous health endpoint answers:

systemctl is-active suwayomi.service nginx.service

curl -fsS http://127.0.0.1/healthz

The first command prints active for both services; the health check prints ok.

Browse sources and extensions

Step 6: Open the Web Reading UI

Open a browser and navigate to http://<public-ip>/. When prompted, sign in with the user name admin and the password from Step 4. The library view loads; it is empty until you add sources and titles.

The Suwayomi server itself binds only to the loopback interface on port 4567 and is never exposed directly. All access goes through the nginx reverse proxy on port 80, which enforces authentication.

Server settings

Step 7: Verify Authentication from the Command Line

Confirm the reader accepts the generated credential and rejects an anonymous request. The first command reads the password from the credentials file and requests the UI as admin; the second confirms an unauthenticated request is refused.

PASS=$(sudo grep '^suwayomi.admin.pass=' /root/suwayomi-credentials.txt | cut -d= -f2-)
curl -fsS -u "admin:${PASS}" -o /dev/null -w 'authenticated: HTTP %{http_code}\n' http://127.0.0.1/
curl -s -o /dev/null -w 'anonymous: HTTP %{http_code}\n' http://127.0.0.1/

The authenticated request returns HTTP 200 and the anonymous request returns HTTP 401.

Step 8: Check the Server Version

Suwayomi exposes a GraphQL API. Query the server version directly on the instance (the loopback API is not behind the reverse proxy):

curl -fsS -H 'Content-Type: application/json' \
  --data '{"query":"{ aboutServer { version buildType } }"}' \
  http://127.0.0.1:4567/api/graphql

This returns the running Suwayomi version and build type as JSON.

Step 9: Add Extension Sources

Suwayomi is compatible with Tachiyomi extension sources. In the web UI, open Browse, then the Extension tab. Add an extension repository (a source repo URL) under the repository settings, then install the extensions you want. Installed sources appear under the Source tab, where you can browse and search catalogs, open a title and add it to your library, and read or download chapters. A built in Local source is available for manga you upload yourself.

Step 10: The Dedicated Data Volume

Your library, downloads, thumbnails, extension sources and the server configuration live on a dedicated EBS data volume mounted at /var/lib/suwayomi, separate from the operating system disk so you can resize or snapshot it independently.

df -h /var/lib/suwayomi

To grow storage later, expand the EBS volume in the AWS console and then grow the filesystem on the instance.

Step 11: Service Management and Maintenance

Suwayomi runs under systemd. Common operations:

systemctl status suwayomi.service --no-pager

To restart the server after changing its configuration at /var/lib/suwayomi/server.conf:

sudo systemctl restart suwayomi.service

The nginx credential store is at /etc/nginx/.suwayomi_htpasswd. To rotate the reader password, regenerate the entry with htpasswd for user admin and reload nginx, then update your saved credentials.

Security

  • Authentication by default. The nginx reverse proxy requires HTTP Basic authentication for every request except the anonymous /healthz endpoint. The Suwayomi server binds only to loopback and is never exposed directly.
  • Per instance credentials. The administrator password is generated uniquely on first boot and stored in /root/suwayomi-credentials.txt (mode 0600). No shared or default reader credential ships in the image.
  • Encryption at rest. Enable AWS EBS encryption when launching the instance, or use encrypted snapshots, to encrypt the data volume that holds your library.
  • Network isolation. Deploy in a private VPC subnet and restrict the security group so that only trusted networks can reach port 80. For access over the public internet, place the instance behind a TLS terminating load balancer or reverse proxy.

Support

cloudimg provides 24/7 technical support for this image via email and live chat. We help with deployment, reverse proxy and authentication setup, extension source configuration, data volume management and backups, JVM administration, and troubleshooting.

For assistance, or to request a refund, contact support@cloudimg.co.uk.