This document covers the installation and deployment of AnythingLLM, focusing on the Docker-based deployment architecture and initial setup requirements. It describes the multi-stage build process, runtime configuration, and deployment options available for getting AnythingLLM running in production or development environments.
For detailed information about configuring system settings after deployment, see Environment Configuration. For information about the CI/CD pipeline and automated builds, see CI/CD and Build Process.
AnythingLLM is designed to run as a single containerized application that includes all three components: the React frontend (built with Vite), Node.js backend server (Express), and Puppeteer-based collector service. The application can be deployed via Docker (recommended for production) or run locally for development.
Deployment Architecture Overview
Sources: docker/Dockerfile1-183 package.json17-19 server/package.json9-10 collector/package.json9-10
| Component | Requirement | Notes |
|---|---|---|
| Node.js | >= 18.12.1 | Specified in engines field in package.json |
| Operating System | Ubuntu Noble (Docker) or any OS with Node 18+ | Base image: ubuntu:noble-20251013 |
| Architecture | AMD64 or ARM64 | Separate build stages for each architecture |
| Disk Space | Minimum 10GB recommended | For documents, vector cache, and models |
| Memory | Minimum 4GB recommended | Depends on LLM provider and workload |
| Network Port | 3001 (default) | Configurable via SERVER_PORT environment variable |
Sources: docker/Dockerfile2 server/package.json9-10 package.json17-19
The Docker deployment uses a sophisticated multi-stage build process that separates the build environment from the runtime environment, optimizing image size and security.
Docker Multi-Stage Build Flow
Sources: docker/Dockerfile1-181
base)The base stage establishes the Ubuntu Jammy foundation with core system dependencies:
Key Dependencies:
uvx 0.6.10 for MCP (Model Context Protocol) supportSources: docker/Dockerfile2-107
ARM64 Stage (build-arm64):
ARM64 requires special handling because Puppeteer does not ship with an ARM-compatible Chromium build. The build downloads and installs a compatible Chromium binary:
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV CHROME_PATH=/app/chrome-linux/chrome
ENV PUPPETEER_EXECUTABLE_PATH=/app/chrome-linux/chrome
Sources: docker/Dockerfile8-72
AMD64 Stage (build-amd64):
Standard setup without Chromium patching, relies on Puppeteer's bundled Chromium.
Sources: docker/Dockerfile77-125
frontend-build)Compiles the React application using Vite:
WORKDIR /app/frontend
RUN yarn install --network-timeout 100000 && yarn cache clean
RUN yarn build
The build output is moved to a temporary location, then the source files are removed to reduce image size, keeping only the compiled dist/ folder.
Sources: docker/Dockerfile141-147
backend-build)Installs production dependencies for both the server and collector services:
WORKDIR /app/server
RUN yarn install --production --network-timeout 100000
WORKDIR /app/collector
ENV PUPPETEER_DOWNLOAD_BASE_URL=https://storage.googleapis.com/chrome-for-testing-public
RUN yarn install --production --network-timeout 100000
Sources: docker/Dockerfile151-161
production-build)Merges the compiled frontend into the server's public directory:
COPY --chown=anythingllm:anythingllm --from=frontend-build /app/frontend/dist /app/server/public
Sets runtime environment variables:
NODE_ENV=productionANYTHING_LLM_RUNTIME=dockerDEPLOYMENT_VERSION=1.11.0Sources: docker/Dockerfile167-174
Container Filesystem and Process Layout
Sources: docker/Dockerfile46-174
Three directories should be mounted as volumes for data persistence:
| Volume Path | Purpose | Critical Data |
|---|---|---|
/app/server/storage/ | Application database and assets | anythingllm.db, uploaded documents, vector cache, LanceDB data |
/app/collector/hotdir/ | Document upload staging area | Temporary files during ingestion |
/app/collector/outputs/ | Processed document output | JSON documents after parsing |
Docker Run Example:
Sources: docker/Dockerfile46-115
The container entry point script (/usr/local/bin/docker-entrypoint.sh) performs initialization tasks before starting the server:
Sources: docker/Dockerfile49-182
The health check script (/usr/local/bin/docker-healthcheck.sh) verifies the container is healthy:
HEALTHCHECK --interval=1m --timeout=10s --start-period=1m \
CMD /bin/bash /usr/local/bin/docker-healthcheck.sh || exit 1
The check runs every minute with a 10-second timeout and a 1-minute startup grace period.
Sources: docker/Dockerfile50-178
For development, AnythingLLM can be run locally without Docker using the provided npm scripts.
Development Setup Process:
Sources: package.json20-39
Initial Setup:
This script:
.env.example files to .env filesyarn prisma:setup to initialize the databaseSources: package.json23-24
Running Services:
Option 1 - Separate terminals:
Option 2 - Concurrent execution:
Sources: package.json25-28
| Script | Purpose | Command |
|---|---|---|
dev:server | Start backend with nodemon | cd server && yarn dev - uses nodemon with ignore flags |
dev:frontend | Start Vite dev server | cd frontend && yarn dev - Vite with HMR |
dev:collector | Start collector service | cd collector && yarn dev - Express API for document processing |
dev:all | Run all three services concurrently | Uses npx concurrently to run server, frontend, and collector |
prisma:generate | Generate Prisma client | cd server && npx prisma generate |
prisma:migrate | Run database migrations | cd server && npx prisma migrate dev --name init |
prisma:seed | Seed database | cd server && npx prisma db seed |
prisma:setup | Full Prisma initialization | Runs generate, migrate, and seed in sequence |
Sources: package.json25-32 server/package.json13-14 collector/package.json13-14
The server initialization follows this sequence when index.js is executed:
Server Initialization Flow
Sources: Based on server startup pattern from Express application structure
Port Configuration:
The server listens on port 3001 by default, configurable via the SERVER_PORT environment variable:
The server listens on the specified port, defaulting to 3001 if SERVER_PORT is not set in the environment.
Sources: Based on standard Express server configuration pattern
HTTPS Mode:
The server can be configured to run in HTTPS mode by setting the ENABLE_HTTPS environment variable and providing SSL certificates in the appropriate directory structure.
Sources: Based on standard Node.js HTTPS server configuration
Static File Serving:
In production mode (NODE_ENV === "production"), the compiled frontend is served from the public/ directory. The Express static middleware is configured with security headers to remove the X-Powered-By header and set X-Frame-Options to DENY.
Sources: Based on Express static file serving configuration in docker/Dockerfile169
The application uses different .env files depending on the deployment mode:
Environment File Hierarchy
Sources: package.json24 docker/Dockerfile51-120
The .env.example file is copied into the container at build time as the default .env file:
This provides default configuration values for first-time setup. After the container starts, configuration can be modified through:
updateENV system - see Configuration Management).env file (requires container restart).env values)Sources: docker/Dockerfile51-120
Before deploying AnythingLLM to production:
/app/server/storage/ (required)/app/collector/hotdir/ (optional but recommended)/app/collector/outputs/ (optional but recommended).env file with necessary provider API keys (see Environment Configuration)http://localhost:3001/api/system endpoint responds/app/server/storage/anythingllm.dbSources: docker/Dockerfile177-178
If web scraping fails on ARM64 systems, verify the Chromium installation:
The environment variables should be set:
PUPPETEER_EXECUTABLE_PATH=/app/chrome-linux/chromeCHROME_PATH=/app/chrome-linux/chromePUPPETEER_SKIP_CHROMIUM_DOWNLOAD=trueSources: docker/Dockerfile63-72
If port 3001 is already in use, specify a custom port:
Note: The container internal port remains 3001; only the host mapping changes.
Sources: Based on Docker port mapping conventions
The container runs as user anythingllm (UID 1000, GID 1000). Ensure mounted volumes have appropriate permissions:
Sources: docker/Dockerfile42-115
If Prisma migrations fail on startup, the database may be corrupted. Reset it:
Sources: package.json33
After successfully deploying AnythingLLM:
Sources: Referenced from table of contents structure
Refresh this wiki