Introduction: UPage is a powerful tool for managing large model APIs and data. This guide helps you deploy UPage on Parrot OS using Docker, with all data stored in /home/v01d/docker/upage for easy management. The process is quick, beginner-friendly, and takes just minutes to set up.


Prerequisites

Ensure your system is ready:


Docker Installed: Recommended Docker 20.10.0 or higher. Not installed? Run:

sudo apt update
sudo apt install docker.io docker-compose -y
System Resources: At least 2GB RAM and 2GB disk space (your Terrans Force T500 handles this easily).
Internet Connection: For pulling images and connecting to APIs (like OpenAI).

sudo usermod -aG docker $USER
Restart your terminal after.
Permissions: Add your user to the docker group:


Step 1: Create the UPage Directory

Store all UPage data, logs, and storage in /home/v01d/docker/upage for organization.

Create the directories:


# Create UPage-specific directories
mkdir -p /home/v01d/docker/upage/{data,logs,storage}


Verify directories


cd /home/v01d/docker/upage

Tip: This directory keeps your data safe across container restarts. Back it up regularly!

Step 2: Pull the UPage Image

Download the latest UPage image from Docker Hub:


docker pull halohub/upage:latest

For a specific version (e.g., 1.0.0), use:


docker pull halohub/upage:1.0.0

Confirm the image downloaded:


docker images | grep upage

Step 3: Set Environment Variables

UPage needs to connect to a large model API (like OpenAI). Prepare:

  • LLM_PROVIDER: E.g., OpenAI.
  • PROVIDER_BASE_URL: API base URL (e.g., https://api.openai.com/v1).
  • PROVIDER_API_KEY: Your API key.
  • LLM_DEFAULT_MODEL: Default model, like gpt-3.5-turbo.
  • LLM_MINOR_MODEL: Backup model, like gpt-4.

Note: Keep these sensitive details private! Plug them into the next step.

Step 4: Start the UPage Container

Launch the container, mapping port 3000 and mounting /home/v01d/docker/upage:

docker run -d \
  --name upage \
  --restart unless-stopped \
  -p 3000:3000 \
  -e LLM_PROVIDER=OpenAI \
  -e PROVIDER_BASE_URL=https://openrouter.ai/api/v1 \
  -e PROVIDER_API_KEY=sk-ABCDEFG1234567 \
  -e LLM_DEFAULT_MODEL=gpt-4o-mini \
  -e LLM_MINOR_MODEL=gpt-4o-mini \
  -v /home/v01d/docker/upage/data:/app/data \
  -v /home/v01d/docker/upage/logs:/app/logs \
  -v /home/v01d/docker/upage/storage:/app/storage \
  halohub/upage:latest

Breakdown:

  • -d: Run in background.
  • --name upage: Names the container for management.
  • --restart unless-stopped: Auto-restart unless stopped manually.
  • -p 3000:3000: Maps port 3000 to host.
  • -e: Sets API environment variables (replace with your values).
  • -v: Mounts subdirectories for data persistence.

Visit http://localhost:3000 to confirm UPage is running.



Container Management

Control your container with these commands:


# Check container status
docker ps | grep upage


View logs (for debugging)


docker logs upage


Stop container


docker stop upage


Start container


docker start upage


Restart container


docker restart upage

Logs are great for troubleshooting.

Upgrading UPage

To upgrade to a new version:

  1. Pull the latest image:

    
docker pull halohub/upage:latest

  2. Stop and remove the old container:

    
docker stop upage
docker rm upage

  3. Restart with the same config (use the launch command above).

Your data in /home/v01d/docker/upage stays safe.

Troubleshooting

  • Port Conflict? Use a different port, like -p 3001:3000, and access http://localhost:3001.
  • Permission Issues? Fix with:
    
sudo chown -R $USER:$USER /home/v01d/docker/upage
  • API Failure? Verify environment variables and network; ensure the API key is valid.
  • Resource Issues?