zelest/stacks repository overview

⁠Stacks - Download Manager for Anna's Archive

⁠Overview

Stacks is a containerized download queue manager designed specifically for Anna's Archive. It provides a clean web interface to queue, manage, and download books automatically. With support for Anna's Archive's fast download API and automatic fallback to mirrors, Stacks ensures reliable downloads with minimal manual intervention.

⁠Key Featurespip

• Secure Web Interface - Password-protected dashboard with session management
• Queue Management - Add books to a download queue from your browser with one click
• Fast Download Support - Utilize Anna's Archive membership for priority downloads
• Automatic Fallback - Seamlessly falls back to mirror sites when fast downloads are unavailable
• Real-time Dashboard - Monitor downloads, queue status, and history
• Browser Integration - Tampermonkey script adds download buttons directly to Anna's Archive
• Docker Ready - Easy deployment with Docker Compose
• Beautiful UI - Dracula-themed interface with live progress tracking
• Resume Support - Automatically resume interrupted downloads
• Download History - Track successful and failed downloads with retry capability

⁠Quick Start

⁠Docker Installation

The fastest way to install Stacks is by using the Docker image available on Docker Hub. You can deploy it with either Docker Compose or the Docker CLI.

⁠Docker Compose

Prerequisites

• Docker and Docker Compose installed
• (Recommended) FlareSolverr for solving Cloudflare/DDoS-guard
• (Optional) Anna's Archive membership for fast downloads

1. Create a file named docker-compose.yaml and add the following:

    networks:
      default:
        name: stacks
   
    services:
      stacks:
        image: zelest/stacks:latest
        container_name: stacks
        stop_signal: SIGTERM
        stop_grace_period: 30s
        ports:
          # Change the left port if 7788 is already in use
          - "7788:7788"
        volumes:
          # REQUIRED - change these paths to match your system
          - /path/to/config:/opt/stacks/config # Configuration files
          - /path/to/download:/opt/stacks/download # Downloaded files
          - /path/to/logs:/opt/stacks/logs # Log files
   
          # OPTIONAL: Separate incomplete folder (requires setting in Stacks UI)
          # Uncomment and set incomplete_folder_path to "/incomplete" in the UI
          # - "/path/to/incomplete:/opt/stacks/incomplete"
   
        restart: unless-stopped
        environment:
          # These only apply on first run, afterward edit config.yaml directly
          # or update the configuration from the UI.
          - USERNAME=admin # Default admin username (change if desired)
          - PASSWORD=stacks # Default admin password - CHANGE THIS!
   
          # Uncomment to reset the admin password to the above values on startup
          # - RESET_ADMIN=true
   
          # If you're using the included flaresolverr, this will automatically
          # connect it. If you already got it running, you can change this
          # address to match your local setup, or delete this variable and set
          # it up inside Stacks later.
          - SOLVERR_URL=flaresolverr:8191
   
          # Set your timezone:
          # https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
          - TZ=UTC
   
      # Optional, but recommended - bypasses Cloudflare and DDoS-Guard
      # protection on mirror sites. Required if you encounter 403 errors when
      # downloading. Not needed for fast downloads.
      flaresolverr:
          image: ghcr.io/flaresolverr/flaresolverr:latest
          container_name: flaresolverr
          ports:
            - "8191:8191"
          environment:
            - LOG_LEVEL=info
          restart: unless-stopped
   

   Copy

2. Update the volume paths to wherever you want Stacks to keep its files.

3. Change PASSWORD to something secure (seriously, do this).

4. In the same directory, run:

   docker compose up
   

   Copy

⁠Docker CLI Installation

If you prefer running Stacks without Docker Compose, you can use the Docker CLI directly.

Prerequisites

• Docker installed
• (Recommended) FlareSolverr for solving Cloudflare/DDoS-guard
• (Optional) Anna's Archive membership for fast downloads

1. Create the required folders on your host:

   mkdir -p /path/to/config /path/to/download /path/to/logs
   

   Copy

2. Set up the network:

   docker network create stacks
   

   Copy

3. Set up FlareSolverr

   docker run -d \
     --name flaresolverr \
     --network stacks \
     -p 8191:8191 \
     -e LOG_LEVEL=info \
     --restart unless-stopped \
     ghcr.io/flaresolverr/flaresolverr:latest
   

   Copy

4. Set up Stacks

   docker run -d \
     --name stacks \
     --network stacks \
     --stop-signal SIGTERM \
     -p 7788:7788 \
     -v /path/to/config:/opt/stacks/config \
     -v /path/to/download:/opt/stacks/download \
     -v /path/to/logs:/opt/stacks/logs \
     -e USERNAME=admin \
     -e PASSWORD=stacks \
     -e SOLVERR_URL=flaresolverr:8191 \
     -e TZ=UTC \
     --restart unless-stopped \
     zelest/stacks:latest
   

   Copy

Important notes

• USERNAME and PASSWORD only apply on first run; afterward Stacks is configured via config.yaml.

• Change the left side of -p 7788:7788 if port 7788 is already taken.

• Always change the default password before exposing Stacks publicly.

• To reset the admin password later, add:

  -e RESET_ADMIN=true
  

  Copy

⁠User access rights

By default, Stacks runs as root inside the container. This is normal fo rmany Docker images, but means that any files created or mounted volumes will also belong to root on the host.

If your other pass can't access the downloaded files, or you prefer stricter permission control, you can tell Docker to run Stacks as a different user.

Set a specific user in Docker Compose

 services:
   stacks:
     # Use previous config and add:
     user: 1000:1000 # Replace with the UID:GID you want Stacks to use

Set a specific user in Docker CLI

docker run -d \
  --user 1000:1000 \
  ...
  zelest/stacks:latest

If Stacks already have created files as root, you may need to update ownership nefore switching users:

sudo chown -R 1000:1000 /path/to/config
sudo chown -R 1000:1000 /path/to/download
sudo chown -R 1000:1000 /path/to/logs

Replace the UID/GID and paths to match your setup.

⁠First-Time Setup

1. Navigate to the web interface at http://localhost:7788
2. Log in with default credentials (or custom if set via environment variables)
3. Go to Settings tab
4. Change your password in the Login Credentials section
5. Copy your API key for usage with the Tampermonkey script in step 9
6. (Optional) Configure your Anna's Archive fast download key⁠ and enable fast downloads.
7. Adjust download delays and retry settings as needed
8. Click Save Settings
9. Install the Tampermonkey Script (see the Tampermonkey documentation⁠ for more information)

⁠Security

Stacks implements multiple layers of security:

• Password Authentication: Bcrypt-hashed passwords with salt
• Session Management: Secure HTTPOnly cookies with SameSite protection
• Rate Limiting: 5 failed login attempts triggers 10-minute lockout
• API Key Authentication: Secure 32-character keys for external tools
• Auto-generated Secrets: API keys and session secrets generated on first run

Security Best Practices:

1. Change the default password immediately after first login
2. Use strong, unique passwords
3. Keep your API key secure
4. Don't expose Stacks directly to the internet without additional security (use a VPN or reverse proxy with HTTPS)

⁠Further reading

• API Manual⁠
• Build your own image⁠
• Configuration⁠
• Tampermonkey installation⁠
• Usage⁠

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠Disclaimer

This tool is for personal use only. Please respect copyright laws and Anna's Archive's terms of service. Support authors and publishers when possible by purchasing their work.