Deployment Guide

This document describes how to deploy OntiCards with Docker Compose in one command.

1. Environment Requirements

2. Quick Deployment (3 Steps)

Step 1: Clone the Project

git clone https://github.com/stepll2026/OntiCards.git
cd onticards

Step 2: Configure Environment Variables

cp .env.prod .env

Edit the .env file and fill in the required settings:

# Database configuration (system's own database)
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=onticards
DB_USER=onticards
DB_PASSWORD=your_password_here

# LLM configuration (required)
LLM_PROVIDER=openai  # or qwen / moonshot / etc.
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=        # If proxy access is needed, fill in the proxy address

# Vector database (optional)
WEAVIATE_URL=http://localhost:8080

# SSO single sign-on (optional; configure when integrating JWT-mode SSO, see User Manual Chapter 15)
SSO_SECRET_KEY=your_sso_shared_secret

Tip: See the comments in the .env.example file for a detailed description of each setting.

Step 3: Start with One Command

docker-compose up -d

Once the containers have started, visit http://localhost:3000

3. Detailed Configuration

3.1 LLM Configuration

OntiCards supports multiple LLM providers:

3.2 Database Configuration

The system uses SQLite as the local database by default (works out of the box with no extra configuration).

To use MySQL/PostgreSQL instead:

DB_TYPE=mysql
DB_HOST=your_mysql_host
DB_PORT=3306
DB_NAME=onticards
DB_USER=onticards
DB_PASSWORD=your_password

3.3 Vector Database (Optional)

The vector database stores data cards. The following options are supported:

To configure Weaviate:

WEAVIATE_URL=http://weaviate:8080
WEAVIATE_API_KEY=your_weaviate_key  # If authentication is required

3.4 Port Configuration

Default port mappings:

To change them, edit the port mappings in docker-compose.yml.

4. Common Operations

4.1 Check Container Status

docker-compose ps

4.2 View Logs

# View logs for all services
docker-compose logs -f

# View backend logs
docker-compose logs -f backend

# View frontend logs
docker-compose logs -f frontend

4.3 Restart Services

docker-compose restart

4.4 Stop Services

docker-compose down

4.5 Update Version

git pull
docker-compose pull
docker-compose up -d

4.6 Backup Data

# Backup the database
docker-compose exec backend tar -czf /backup/db.tar.gz /app/data/

# Copy the backup file out
docker-compose cp backend:/backup/db.tar.gz ./backup/

5. Frequently Asked Questions

5.1 Startup Fails — What to Do?

1. Check whether Docker is running properly:

   docker --version
   docker-compose --version

1. Inspect the logs to locate the problem:

   docker-compose logs -f

1. Confirm the port is not already occupied:

   netstat -an | grep 3000  # Windows
   # or
   lsof -i :3000           # Linux/Mac

5.2 LLM Calls Failing?

1. Make sure the API Key is configured correctly

1. Check whether the network can reach the LLM provider

1. If a proxy is required, ensure LLM_BASE_URL points to the correct proxy address

5.3 Database Connection Failing?

1. Confirm the target database is reachable over the network

1. Check the firewall settings

1. Confirm the username and password are correct

6. Production Deployment

6.1 HTTPS Configuration

It is recommended to terminate HTTPS with an Nginx reverse proxy:

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
    }

    location /api {
        proxy_pass http://localhost:8000;
    }
}

6.2 Capacity Planning

6.3 Data Persistence

Make sure the data in the following directories or volumes is backed up on a regular basis:

• Database files (data/ directory)

• Vector database data

• Configuration files (.env)

7. Uninstall

# Stop and remove containers
docker-compose down

# Remove data (caution: this will erase all data)
docker-compose down -v

# Remove project files
cd ..
rm -rf onticards

8. Getting Help

• See first-time usage flow to learn the basics

• See the troubleshooting guide to resolve common issues

• Submit an Issue: https://github.com/stepll2026/OntiCards/issues