Skip to main content
This guide will help you deploy Nanahoshi using Docker Compose. You’ll have a fully functional digital library server with web interface, database, search, and background workers.

​
Prerequisites

Before you begin, ensure you have:
  • Docker and Docker Compose installed
  • At least 2GB of available RAM (for Elasticsearch)
  • A directory containing your ebook files (EPUB or other supported formats)

​
Installation steps

1

Clone the repository

Clone the Nanahoshi repository to your local machine:
git clone https://github.com/Natsume-197/nanahoshi.git
cd nanahoshi
2

Configure environment variables

Copy the example environment file and edit it with your values:
cp .env.example .env
Open .env in your text editor and configure the required variables:
.env
# Generate a stable UUID for deterministic book IDs
NAMESPACE_UUID=00000000-0000-0000-0000-000000000000  # Replace with: uuidgen

# Secret for signing download URLs
DOWNLOAD_SECRET=00000000-0000-0000-0000-000000000000  # Replace with: uuidgen

# Authentication secret (min 32 characters)
BETTER_AUTH_SECRET=change-me-to-a-random-string-at-least-32-chars  # Replace with: openssl rand -hex 32

# Email configuration for user invitations and notifications
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=[email protected]
SMTP_PASS=your-app-password

# Database password
POSTGRES_PASSWORD=password  # Change to a secure password

# Redis password
REDIS_PASSWORD=change-me  # Change to a secure password

# Optional: customize ports
SERVER_PORT=3000
WEB_PORT=3001

# Optional: customize search index prefix
ELASTICSEARCH_INDEX_PREFIX=nanahoshi
You can generate secure random values using:
  • uuidgen for UUIDs
  • openssl rand -hex 32 for secrets
3

Configure book library volumes

Edit docker-compose.yml to mount your book directories. Locate the server service and add your book paths under volumes:
docker-compose.yml
services:
  server:
    volumes:
      - server_data:/app/apps/server/data
      # Add your book directories here (read-only recommended)
      - /path/to/your/manga:/books/manga:ro
      - /path/to/your/novels:/books/novels:ro
      - /path/to/your/audiobooks:/books/audiobooks:ro
Replace the example paths with your actual book directories. The :ro flag mounts them as read-only for safety.
The paths on the left side (/path/to/your/manga) are paths on your host machine. The paths on the right side (/books/manga) are paths inside the container. You’ll use the container paths when creating libraries in the admin UI.
4

Start the services

Launch all services with Docker Compose:
docker compose up -d --build
This command will:
  • Build the server and web containers
  • Start PostgreSQL, Redis, and Elasticsearch
  • Run database migrations automatically
  • Start background workers for scanning and indexing
The first startup may take a few minutes as Docker downloads images and builds containers.
5

Access Nanahoshi

Once the containers are running, you can access:
If you customized SERVER_PORT or WEB_PORT in your .env file, use those ports instead.
6

Create your first library

After logging in to the web interface:
  1. Navigate to the admin section
  2. Create a new library
  3. Set the library path to match the container mount point (e.g., /books/manga)
  4. Enable automatic scanning if desired
  5. Save the library
Nanahoshi will begin scanning your books and extracting metadata. You can monitor the progress in the Bull Board dashboard at http://localhost:3000/admin/queues/.

​
Verify installation

To verify that all services are running correctly: 
docker compose ps
You should see five containers running:
  • nanahoshi-v2-server - Backend API and workers
  • nanahoshi-v2-web - Frontend application
  • nanahoshi-v2-postgres - PostgreSQL database
  • nanahoshi-v2-redis - Redis for job queues
  • nanahoshi-v2-elasticsearch - Search indexing

​
View logs

If you encounter issues, check the logs: 
# View all logs
docker compose logs -f

# View logs for a specific service
docker compose logs -f server
docker compose logs -f web

​
Stop and restart

To stop Nanahoshi: 
docker compose down
To restart: 
docker compose up -d

​
Update Nanahoshi

To update to the latest version: 
git pull
docker compose up -d --build
Database migrations will run automatically on startup.

​
Data persistence

Nanahoshi stores persistent data in Docker volumes:
  • postgres_data - Database tables and user data
  • es_data - Elasticsearch search indices
  • server_data - Book covers, metadata cache, and application files
These volumes persist even when you stop or restart containers.
To completely reset Nanahoshi and delete all data:
docker compose down
docker volume rm nanahoshi-v2_postgres_data nanahoshi-v2_es_data nanahoshi-v2_server_data
This action is irreversible.

​
Troubleshooting

​
Elasticsearch fails to start

Elasticsearch requires at least 2GB of RAM. If you’re on Linux, you may also need to increase the vm.max_map_count setting: 
sudo sysctl -w vm.max_map_count=262144
To make this permanent, add it to /etc/sysctl.conf.

​
Books aren’t showing up

Verify that:
  1. Your book directories are correctly mounted in docker-compose.yml
  2. The library path in the admin UI matches the container mount point (e.g., /books/manga)
  3. The scanner worker is running (check logs: docker compose logs -f server)
  4. Your book files are in a supported format (EPUB, etc.)

​
Can’t log in

Check that:
  1. BETTER_AUTH_SECRET is set in your .env file
  2. SMTP_* variables are configured correctly for sending email
  3. The database migrations completed successfully (check logs)

​
What’s next?

Installation

Set up a development environment to contribute to Nanahoshi

Configuration

Learn about advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us