Skip to main content
Docker is the recommended way to run Lightnovel Crawler in a reproducible, portable environment. The official image is published to GitHub Container Registry and includes Calibre, so all output formats work out of the box.

​
Quick setup

1

Pull the image

docker pull ghcr.io/lncrawl/lightnovel-crawler
2

Tag it for convenience

docker tag ghcr.io/lncrawl/lightnovel-crawler lncrawl
3

Create a data directory

mkdir -p ~/.lncrawl
The container writes all data (database, downloaded novels, artifacts) to /data, which you map to this host directory via a volume mount.
4

Run lncrawl

docker run -v ~/.lncrawl:/data --rm -it lncrawl

​
Docker alias

To avoid typing the full docker run command every time, add an alias to your shell profile (~/.bashrc, ~/.zshrc, etc.): 
alias docker-lncrawl='docker run -v ~/.lncrawl:/data --rm -it -p 8080:8080 lncrawl'
Then use it like a local install: 
docker-lncrawl server
docker-lncrawl crawl --all -f epub https://novelfull.com/my-novel.html

​
Volume mount

The container reads and writes all persistent data through the /data path, set by the LNCRAWL_DATA_PATH environment variable.
Host pathContainer pathPurpose
~/.lncrawl/dataDatabase, novel files, artifacts, config
You can override the data path: 
docker run -v /mnt/storage/lncrawl:/data -p 8080:8080 --rm -it lncrawl server

​
Environment variables

VariableDefaultDescription
LNCRAWL_DATA_PATH/dataPath inside the container where all data is stored.
DATABASE_URLSQLite in /dataOverride with a PostgreSQL URL for production use.
SELENIUM_GRIDURL to a Selenium Grid for JavaScript-heavy sites (e.g. http://chrome:4444).
PYTHONUNBUFFEREDSet to 1 to get real-time log output.

​
Building from source

If you want to build the image yourself: 
# Build base image (Calibre + system deps) then application image
make docker-build

# Equivalent manual command (requires the base image to already exist)
docker build -t lncrawl .

​
Docker Compose

The repository includes a local Docker Compose file at scripts/local-compose.yml that wires together the app server, a PostgreSQL database, and a Selenium Chrome node for JavaScript-heavy sites. 
# Start the full stack in the background
make docker-up
# or: docker compose -f scripts/local-compose.yml up -d

# Stop the stack
make docker-down

# Stream container logs
make docker-logs
The compose stack exposes:
ServicePortDescription
server8080Lightnovel Crawler web server
postgres5432PostgreSQL database
chrome4444, 7900Selenium Chrome node
For production deployments, use scripts/server-compose.yml as a starting point. It references the published ghcr.io/lncrawl/lightnovel-crawler:latest image and omits the Chrome node by default.

Build docs developers (and LLMs) love

Get started for freeTalk to us