Deploying Atsumeru

Atsumeru (集める, Japanese for “to collect”) is a free, open-source, self-hosted media server designed specifically for manga, comics, and light novels enthusiasts. Built with Java and Spring Boot, Atsumeru provides a powerful platform to organize, manage, and read your digital library from anywhere using native client applications.

Whether you have a collection of manga volumes, comic book archives, or light novel series, Atsumeru helps you organize everything into a structured library with rich metadata support, multiple user accounts, and seamless synchronization across devices.

Multi-Format Support

CBZ, CBR, CB7, PDF, ePub, FB2, and Djvu formats

Native Apps

Clients for Windows, Linux, Mac, and Android

Smart Organization

Auto-categories, custom categories, and metacategories

Metadata Management

ComicInfo.xml and book_info.json support with catalog parsing

Key Features

Atsumeru provides comprehensive features for managing your digital manga and comics library:

Feature	Description
Library Organization	Sort content into series, categories, and custom collections
Metadata Import	Auto-import from ComicInfo.xml and book_info.json formats
Catalog Parsing	Parse metadata from supported online catalogs
Multi-User Support	Create separate accounts with individual history and permissions
Reading Progress Sync	Two-way synchronization of reading history across devices
Series Download	Download entire series through supported applications
REST API	Full API access with Swagger documentation
Access Controls	Granular permissions for library access

Supported File Formats

Format	Extension	Notes
Comic Book ZIP	.cbz	Full support
Comic Book RAR	.cbr	Full support
Comic Book 7-Zip	.cb7	Full support
PDF	.pdf	Full support
ePub	.epub	With limitations
FictionBook	.fb2	With limitations
DjVu	.djvu	Full support

Prerequisites

Before deploying Atsumeru on Klutch.sh, ensure you have:

• A Klutch.sh account with an active project
• A GitHub repository for your deployment configuration
• Your manga/comics library ready to upload or accessible via cloud storage

Project Structure

Set up your Atsumeru deployment:

• Directoryatsumeru-server/

  • Dockerfile
  • docker-compose.yml (local development)
  • README.md

Deployment Configuration

Dockerfile

Create a Dockerfile for your Atsumeru deployment:

Dockerfile

FROM atsumerudev/atsumeru:latest

# Expose the default Atsumeru port
EXPOSE 31337

# Create necessary directories
RUN mkdir -p /library /app/config /app/database /app/cache /app/logs

# Set working directory
WORKDIR /app

# Default command (already set in base image)
CMD ["java", "-jar", "Atsumeru.jar"]

Custom Dockerfile with Health Check

For enhanced monitoring and reliability:

Dockerfile

FROM atsumerudev/atsumeru:latest

# Expose the default Atsumeru port
EXPOSE 31337

# Create necessary directories
RUN mkdir -p /library /app/config /app/database /app/cache /app/logs

# Set permissions
RUN chmod -R 755 /library /app

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:31337/ || exit 1

WORKDIR /app

CMD ["java", "-jar", "Atsumeru.jar"]

Volume Configuration

Atsumeru requires several directories for proper operation:

Mount Path	Purpose
/library	Your manga/comics/light novels files
/app/config	Server configuration files
/app/database	SQLite databases for library metadata
/app/cache	Cover image cache
/app/logs	Server log files

Local Development with Docker Compose

Test your Atsumeru setup locally:

docker-compose.yml

services:
  atsumeru:
    image: atsumerudev/atsumeru:latest
    container_name: atsumeru
    ports:
      - "31337:31337"
    volumes:
      - ./library:/library
      - atsumeru-config:/app/config
      - atsumeru-db:/app/database
      - atsumeru-cache:/app/cache
      - atsumeru-logs:/app/logs
    restart: unless-stopped

volumes:
  atsumeru-config:
  atsumeru-db:
  atsumeru-cache:
  atsumeru-logs:

Tip

Run docker compose up -d to start Atsumeru locally. Check docker logs atsumeru to find the auto-generated admin password on first startup.

Deploying to Klutch.sh

1. Push your repository to GitHub

   1. Initialize your Git repository and commit the Dockerfile

   git init
   git add .
   git commit -m "Initial Atsumeru configuration"
   git remote add origin https://github.com/yourusername/atsumeru-server.git
   git push -u origin main

2. Create a new app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project or create a new one
   3. Click Create App and connect your GitHub repository
   4. Klutch.sh will automatically detect your Dockerfile

3. Configure the internal port

   1. Set the internal port to 31337 (Atsumeru’s default port)
   2. Select HTTP as the traffic type

4. Set up persistent storage

   1. Add persistent volumes for your Atsumeru data

   Mount Path	Size	Purpose
   /library	50 GB+	Your manga/comics library (adjust based on collection size)
   /app/config	100 MB	Configuration files
   /app/database	1 GB	Library metadata database
   /app/cache	5 GB	Cover image cache
   /app/logs	500 MB	Server logs

   Note

   Adjust the /library volume size based on your collection. A typical manga volume is 50-200MB, so plan accordingly.

5. Deploy your application

   1. Click Deploy to build and launch your Atsumeru server
   2. Monitor the build logs for any issues
   3. Once deployed, your server will be available at https://your-app.klutch.sh

6. Retrieve admin credentials

   1. Check the deployment logs to find the auto-generated admin password
   2. Look for a line containing the admin credentials
   3. Save these credentials securely for initial login

Important

On first startup, Atsumeru generates a random password for the Admin user. Make sure to check your deployment logs immediately to retrieve this password, as you’ll need it to access the server.

Initial Server Setup

First Login

After deployment, access your Atsumeru server:

1. Navigate to https://your-app.klutch.sh
2. Log in with username Admin and the generated password from logs
3. You’ll be prompted to change your password on first login

Adding Your Library

Upload your manga/comics to the /library volume:

1. Use SFTP, rsync, or cloud sync tools to upload files
2. Organize files into folders by series for better organization
3. Supported structures:
   • /library/Manga/Series Name/Volume 01.cbz
   • /library/Comics/Publisher/Series Name/Issue 001.cbz
   • /library/Light Novels/Series Name/Volume 01.epub

Importing Library

After uploading files:

1. Access the Atsumeru web interface
2. Go to Settings → Library
3. Add your library path (/library)
4. Click Scan to import your collection
5. Atsumeru will parse metadata and generate covers

Client Applications

Connect to your Atsumeru server with official client apps:

Atsumeru (Android)

Full-featured reader with sync support

Atsumeru Manager

Desktop app for Windows/Linux/Mac

AniLabX (Android)

Alternative Android client with Atsumeru support

Connecting a Client

Configure your client application:

1. Open the Atsumeru client app
2. Add a new server connection
3. Enter your server URL: https://your-app.klutch.sh
4. Enter your username and password
5. Test the connection and save

API Documentation

Atsumeru provides a comprehensive REST API with Swagger documentation:

Accessing Swagger UI

Visit https://your-app.klutch.sh/swagger-ui/index.html to explore the API.

API Authentication

# Get authentication token
curl -X POST "https://your-app.klutch.sh/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "Admin", "password": "your-password"}'

Example API Requests

# List all series
curl "https://your-app.klutch.sh/api/series" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get series details
curl "https://your-app.klutch.sh/api/series/{series-id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Search library
curl "https://your-app.klutch.sh/api/search?query=manga+title" \
  -H "Authorization: Bearer YOUR_TOKEN"

Metadata Management

ComicInfo.xml Format

Atsumeru automatically reads ComicInfo.xml metadata from CBZ/CBR files:

ComicInfo.xml

<?xml version="1.0" encoding="utf-8"?>
<ComicInfo>
  <Series>My Manga Series</Series>
  <Number>1</Number>
  <Volume>1</Volume>
  <Title>Chapter Title</Title>
  <Summary>Description of the volume...</Summary>
  <Year>2024</Year>
  <Month>1</Month>
  <Writer>Author Name</Writer>
  <Penciller>Artist Name</Penciller>
  <Publisher>Publisher Name</Publisher>
  <Genre>Action, Adventure</Genre>
  <LanguageISO>en</LanguageISO>
  <Manga>Yes</Manga>
</ComicInfo>

book_info.json Format

Atsumeru’s native metadata format with extended fields:

book_info.json

{
  "title": "My Manga Series",
  "alt_title": "Alternative Title",
  "volume": 1,
  "chapter": null,
  "description": "Series description...",
  "year": 2024,
  "authors": ["Author Name"],
  "artists": ["Artist Name"],
  "publisher": "Publisher Name",
  "genres": ["Action", "Adventure"],
  "tags": ["tag1", "tag2"],
  "language": "en",
  "country": "JP",
  "status": "ONGOING",
  "content_rating": "EVERYONE",
  "parody": null,
  "circles": [],
  "magazines": [],
  "characters": [],
  "events": []
}

User Management

Creating Users

Add additional users through the web interface or API:

1. Log in as Admin
2. Navigate to Settings → Users
3. Click Add User
4. Set username, password, and permissions
5. Assign library access

Permission Levels

Permission	Description
Admin	Full server access and configuration
User	Read access to assigned libraries
Restricted	Limited access with content filtering

Organization Features

Categories

Organize your library with different category types:

• Auto-categories: Automatically generated based on metadata (genre, author, year)
• Custom categories: User-defined collections
• Metacategories: Combine multiple categories

Series Grouping

Atsumeru automatically groups related content:

1. Volumes of the same series are grouped together
2. Reading progress tracked per series
3. Series-level metadata aggregation

Troubleshooting

Common issues and solutions:

Issue	Cause	Solution
Admin password not in logs	Logs cleared or missed	Delete /app/config volume and redeploy
Covers not generating	Cache directory issue	Ensure /app/cache volume is mounted
Files not appearing	Wrong library path	Verify files are in /library directory
Slow scanning	Large library	Be patient; initial scan takes time
CBR files not reading	RAR dependencies	Ensure using official Docker image

Checking Logs

View server logs for debugging:

# If running locally
docker logs atsumeru

# Check specific log files in /app/logs volume

Re-scanning Library

Force a library rescan:

1. Go to Settings → Library
2. Click Force Rescan
3. Wait for the scan to complete

Performance Optimization

Cache Management

Atsumeru caches cover images for faster loading:

• Covers are generated on first access
• Cache stored in /app/cache
• Clear cache if experiencing display issues

Database Optimization

The SQLite database in /app/database contains:

• Library metadata
• User information
• Reading progress
• Category assignments

Back up this directory regularly for data protection.

Security Best Practices

Change Admin Password

Change the auto-generated admin password immediately

HTTPS Enabled

Klutch.sh provides automatic SSL certificates

User Permissions

Create separate accounts for different users

Regular Backups

Back up /app/database and /app/config regularly

Additional Resources

• Atsumeru Official Website
• Atsumeru GitHub Repository
• Official Docker Documentation
• Atsumeru Guides
• Docker Hub Image
• Atsumeru Telegram Community