Skip to content

server.md

Latest commit

 

History

History
113 lines (98 loc) · 4.8 KB

server.md

File metadata and controls

113 lines (98 loc) · 4.8 KB

Server Deployment Guide

This guide describes the quickest path to deploy CLARITY Convertor on a fresh Linux server and expose it to remote clients.

1. Prerequisites

  • A non-root user with sudo privileges.
  • Docker Engine and Docker Compose Plugin installed. 
    sudo apt-get update
sudo apt-get install ca-certificates curl gnupg lsb-release -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

2. Fetch the Project

cd /opt
sudo git clone <your-repo-url> clarity-convertor
sudo chown -R $USER:$USER clarity-convertor
cd clarity-convertor

3. Environment Configuration

Edit docker-compose.yml to suit the server:

  • SECRET_KEY for JWT signing.
  • REACT_APP_API_BASE_URL build arg under the frontend service (defaults to /api, matching the bundled nginx proxy).
  • OLLAMA_API_URL under the backend service if Ollama runs outside the Compose stack. Use a resolvable hostname or IP and the port where Ollama listens (e.g. http://clarity.iitj.ac.in:11434). When targeting the host machine from inside Docker on Linux, add: 
    extra_hosts:
  - "host.docker.internal:host-gateway"
    and set OLLAMA_API_URL to http://host.docker.internal:11434.
  • OLLAMA_TIMEOUT_SECONDS controls the per-request timeout between the backend and Ollama. Set it to 0 (default) to disable the timeout, or a positive value in seconds for an upper bound.

If Ollama runs directly on the host, ensure it listens on all interfaces:

sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf >/dev/null <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama

Verify the listener:

sudo ss -tulpn | grep 11434

The built-in nginx configuration proxies /api/* back to the FastAPI service, so browser calls automatically reach the backend without exposing port 8000 publicly unless you want direct API access.

4. Build and Run

docker compose up -d --build

Services start under the default ports:

  • Frontend (nginx) → 0.0.0.0:3000
  • Backend (FastAPI) → 0.0.0.0:8000
  • Postgres → 0.0.0.0:5432

Check status:

docker compose ps

5. Expose the Application

Open the necessary ports on the server firewall so external users can connect.

Using UFW

sudo ufw allow 3000/tcp    # React frontend
sudo ufw allow 8000/tcp    # FastAPI API (optional if only the frontend is exposed)
sudo ufw allow 5432/tcp    # Only if remote DB access is required
sudo ufw reload

Using Security Groups (cloud providers)

Add inbound rules for TCP ports 3000 and 8000 from your trusted CIDR ranges.

If you prefer to expose the site on standard HTTP/HTTPS ports, modify docker-compose.yml:

  frontend:
    ports:
      - "80:80"
      - "443:80"   # Front the container with a TLS terminator such as Caddy or nginx-proxy

Then update DNS or load balancer rules accordingly.

6. Verify

  • Visit http://<server-ip>:3000 in a browser.
  • Confirm API health at http://<server-ip>:3000/api/ (proxied) or directly at http://<server-ip>:8000/ / /docs if that port is exposed.
  • If Ollama runs externally, verify connectivity from the backend container: 
    docker compose exec backend curl -sS http://host.docker.internal:11434/api/tags
    Replace the URL with the hostname/IP you configured.
  • Use check_ollama_endpoint.py for a more detailed connectivity check if needed.
  • Log in with the seeded admin account (lakshay / 1312), then update the password immediately.

7. Maintenance

  • Stop the stack: docker compose down
  • Tail logs: docker compose logs -f backend frontend
  • Update the app: pull latest code, then docker compose up -d --build
  • Backup data: archive the backend/uploads/ directory and dump Postgres (docker compose exec db pg_dump -U user clarity_db > clarity_db.sql).

8. Hardening Tips

  • Change default credentials and rotate the SECRET_KEY.
  • Restrict Postgres to local connections unless remote clients are required.
  • Run the frontend behind a reverse proxy (Caddy/nginx) that terminates TLS and handles domain routing.
  • Enable automatic Docker updates or rebuild the stack regularly to pick up security patches.
  • Monitor Ollama availability; large PDFs can take several minutes per conversion, so keep OLLAMA_TIMEOUT_SECONDS aligned with your expectations and watch backend logs for 504 responses.