Deploy Oxy on GCP

This guide walks you through deploying Oxy on Google Cloud Platform using Compute Engine VM instances. We’ll cover everything from setting up a virtual machine to configuring Oxy with proper data persistence and HTTPS access.

This is part of our Hands-on Deployment Guides. For additional deployment options, see our Docker Deployment Guide or the general deployment overview.

Prerequisites

Before you begin, make sure you have:

A Google Cloud Platform account
A domain name (optional, but recommended for production deployments)
Basic familiarity with Linux command line

Getting a VM Instance

Follow these steps to create a VM instance in Google Cloud Platform:

Access Google Cloud Console

Go to the Google Cloud Console and sign in with your account.

Create or Select a Project

Select an existing project or create a new one using the project selector at the top of the page.

Navigate to Compute Engine

From the navigation menu, select Compute Engine > VM instances.

If this is your first time using Compute Engine, you might need to enable the API.

Create a VM Instance

Click the CREATE INSTANCE button and configure your instance:

Name: Choose a name for your instance (e.g., oxy-server)
Region & Zone: Select a region close to your users
Machine Configuration:
- For optimal cost-performance, consider using ARM-based instances (T2A series):
  - t2a-standard-1 (1 vCPU ARM, 4 GB memory)
Boot disk:
- Operating System: Ubuntu
- Version: Latest stable (e.g., Ubuntu 22.04)
- Size: recommended starting point 10 GB
Firewall:
- Check “Allow HTTP traffic”
- Check “Allow HTTPS traffic”

Click Create to provision your VM.

Note Your External IP

Once your VM is ready, note the External IP address displayed in the VM instances list. You’ll need this to connect to your instance and to configure your domain DNS settings if using a custom domain.

Pointing Your Domain to the VM (Optional)

If you have a domain name you want to use for your Oxy deployment:

Access DNS Settings

Go to your domain registrar’s website (such as GoDaddy, Namecheap, or Google Domains) and navigate to the DNS settings for your domain.

Add DNS Records

Add the following DNS records:

A Record:
- Host/Name: @ (represents the root domain)
- Value/Points to: Your VM’s External IP address
- TTL: 3600 (or as recommended by your registrar)
A Record for www subdomain:
- Host/Name: www
- Value/Points to: Your VM’s External IP address
- TTL: 3600 (or as recommended by your registrar)

Wait for DNS Propagation

DNS changes can take from a few minutes to several hours to propagate. You can check the status using online tools like whatsmydns.net.

Setting Up the VM

Connect to your VM instance and prepare it for Oxy deployment:

Connect to Your VM

You can connect directly from the Google Cloud Console by clicking the “SSH” button next to your instance, or use a terminal:

# If using gcloud CLI
gcloud compute ssh --project=YOUR_PROJECT_ID --zone=YOUR_ZONE oxy-server

# Or using standard SSH if you've set up SSH keys
ssh username@EXTERNAL_IP

Update System and Install Essential Packages

# Update package lists and install essential tools in one command
sudo apt update && sudo apt install -y curl wget git unzip jq nano

Installing Oxy CLI

Let’s install Oxy directly on the VM:

Install Required Dependencies

# Install all necessary dependencies at once
sudo apt update && sudo apt install -y build-essential libssl-dev pkg-config

Install Oxy

Run the official Oxy installation script:

bash <(curl --proto '=https' --tlsv1.2 -sSf https://get.oxy.tech)

This script will download and install the latest stable version of Oxy.

Verify the Installation

Confirm that Oxy is installed correctly:

oxy --version

You should see the version information displayed.

Setting Up Oxy Workspace

Let’s use the built-in oxy init command to initialize a new workspace with all the necessary files and configuration:

Create and Navigate to Workspace Directory

mkdir -p ~/oxy-workspace
cd ~/oxy-workspace

Initialize Oxy Project

oxy init

This interactive command will:

Create a config.yml file with your database and model configurations
Set up sample project files
Create necessary directories like agents and workflows

Follow the prompts to configure:

Database settings (You can start with DuckDB for simplicity)
Model configuration (e.g., OpenAI with your API key)

The initialization process will ask for your OpenAI API key and create all the necessary configuration.

Alternative: Set Up Git and Clone Existing Project

If you already have an existing Oxy project in a Git repository, you should set up Git and clone your repository instead of using oxy init.

First, make sure Git is properly configured:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Then clone your existing repository:

git clone https://github.com/yourusername/your-oxy-project.git ~/oxy-workspace
cd ~/oxy-workspace

This will give you your existing project configuration and agents, which is preferable to starting from scratch if you already have a working setup.

Create Data Directory

mkdir -p ~/oxy-data

This directory will store all persistent data for Oxy, including the SQLite database files.

Configure Environment Variables

Create a standard .env file in the workspace directory:

cd ~/oxy-workspace
nano .env

Add your environment variables:

OXY_STATE_DIR=/home/$(whoami)/oxy-data

Save and exit.

If you don’t set OXY_STATE_DIR, Oxy will use the default location ~/.local/share/oxy/. We recommend setting it explicitly for production deployments to make backups and maintenance easier.

Note: You won’t need to manually set the OpenAI API key in the environment as it’s already configured during the oxy init process.

Installing and Configuring Caddy

Now, let’s install and configure Caddy as a reverse proxy for HTTPS and authentication:

Install Caddy

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Create Caddyfile

sudo nano /etc/caddy/Caddyfile

For domain-based setup (recommended):

yourdomain.com {
    reverse_proxy localhost:3000 {
        flush_interval -1
    }
}

Replace yourdomain.com with your actual domain name.

If you don’t have a domain and want to use the IP address only, use:

:80 {
    reverse_proxy localhost:3000 {
        flush_interval -1
    }
}

Save and exit (Ctrl+X, then Y, then Enter).

Configure Authentication (Optional)

To add basic authentication protection:

# Generate a password hash
sudo caddy hash-password
# Enter your desired password when prompted and copy the hash

# Edit Caddyfile to add authentication
sudo nano /etc/caddy/Caddyfile

Update your Caddyfile to add the basicauth directive. You’ll need to choose a username and use the password hash:

yourdomain.com {
    basicauth {
        your_chosen_username YOUR_PASSWORD_HASH
    }
    reverse_proxy localhost:3000 {
        flush_interval -1
    }
}

Replace your_chosen_username with your preferred username and YOUR_PASSWORD_HASH with the hash you generated.

Save and exit (Ctrl+X, then Y, then Enter).

Reload Caddy

sudo systemctl reload caddy

Setting Up and Starting Oxy as a Service

Let’s configure Oxy to run automatically on system startup and restart if it fails:

Create a Systemd Service File

sudo nano /etc/systemd/system/oxy.service

Add the following content:

[Unit]
Description=Oxy Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/oxy-workspace
EnvironmentFile=/home/ubuntu/oxy-workspace/.env
ExecStart=/usr/local/bin/oxy serve --port 3000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

This configuration uses the default ubuntu user which is standard on GCP instances. If you’re using a different username, adjust accordingly.

Save and exit.

Enable and Start the Service

sudo systemctl daemon-reload
sudo systemctl enable oxy
sudo systemctl start oxy

Verify the Service

sudo systemctl status oxy

You should see that the service is active and running.

View Logs (if needed)

If you encounter any issues, check the logs:

sudo journalctl -u oxy -f

This command will show you the live logs from the Oxy service.

Test the Connection

You can test if Oxy is responding properly:

curl http://localhost:3000

You should get a positive response indicating that Oxy is running.

Access Your Deployment

If you’ve set up a domain, open your browser and navigate to your domain:

https://yourdomain.com

Or if you’re using the IP address directly:

http://YOUR_VM_IP

If you’ve set up a domain with DNS earlier, now is the exciting moment to see your work! Open your browser and visit your domain to see the Oxy interface up and running on your own server.

You should see the Oxy interface. Congratulations! 🎉 You’ve successfully deployed Oxy on Google Cloud Platform.

Optional Configuration and Management

Everything up to this point completes the core setup of your Oxy deployment. The following sections cover additional aspects of managing your deployment that you may want to explore as needed.

Data Persistence

It’s important to understand how Oxy handles data persistence:

Oxy uses SQLite for its internal database by default
All data is stored in the directory specified by OXY_STATE_DIR environment variable (we set it to ~/oxy-data)
If OXY_STATE_DIR is not set, Oxy uses ~/.local/share/oxy/ by default
This directory contains database files, semantic information, cached query results, and workflow history

For production deployments, consider backing up the oxy-data directory regularly. You can set up automated backups to Google Cloud Storage using gsutil or use a persistent disk for enhanced reliability.

Managing Your Deployment

Stopping the Services

If you need to stop the Oxy service temporarily:

sudo systemctl stop oxy

To stop the Caddy service:

sudo systemctl stop caddy

Updating Oxy

To update Oxy to the latest version:

# Stop the service first
sudo systemctl stop oxy

# Run the installation script again
bash <(curl --proto '=https' --tlsv1.2 -sSf https://get.oxy.tech)

# Start the service again
sudo systemctl start oxy

Backup Data

# Create a backup of your Oxy data
tar -czf oxy-backup-$(date +%Y%m%d).tar.gz ~/oxy-data/

# Optional: Upload to Google Cloud Storage
gsutil cp oxy-backup-*.tar.gz gs://your-bucket-name/

You’ll need the gcloud CLI installed and authenticated for the last command.

Machine Recommendations

Oxy runs well with just 4GB of memory for most use cases.

Choose from these recommended instance types:

Usage Level	ARM-based (Best Value)	x86-based
Small (1-3 users)	`t2a-standard-1` (2 vCPU, 4 GB)	`e2-medium` (1 vCPU, 4 GB)
Medium (3-5 users)	`t2a-standard-2` (2 vCPU, 8 GB)	`e2-standard-2` (2 vCPU, 8 GB)
Large (5-15 users)	`t2a-standard-4` (4 vCPU, 16 GB)	`e2-standard-4` (4 vCPU, 16 GB)

ARM-based instances (T2A series) typically offer 15-20% cost savings over equivalent x86 instances.

Scaling on GCP

As your usage grows, you may need to scale your deployment:

Vertical Scaling

Stop your VM from the GCP Console
Edit the VM configuration to increase CPU and memory
Start the VM again

Reconnect and start your Oxy services:

sudo systemctl start oxy
sudo systemctl start caddy

Storage Scaling

If you need more storage for your Oxy data:

Create a new persistent disk in the GCP Console

Connect to your VM and mount the disk:

# Mount the disk to a new location
sudo mkdir -p /mnt/oxy-data
sudo mount -o discard,defaults /dev/disk/by-id/google-[DISK_NAME] /mnt/oxy-data
sudo chown -R ubuntu:ubuntu /mnt/oxy-data

# Copy your existing data to the new location
cp -r ~/oxy-data/* /mnt/oxy-data/

# Update the data path in your .env file
echo "OXY_STATE_DIR=/mnt/oxy-data" > ~/oxy-workspace/.env

# Restart Oxy to use the new location
sudo systemctl restart oxy

To make the mount persistent across reboots, add it to fstab:

echo "/dev/disk/by-id/google-[DISK_NAME] /mnt/oxy-data ext4 discard,defaults 0 2" | sudo tee -a /etc/fstab

Troubleshooting

Cannot access Oxy through the domain or IP

Caddy cannot obtain SSL certificate

Oxy service won't start

Data not persisting between restarts

For further help, join our community on Discord.

Next Steps

Once your GCP deployment is running:

Configure agents and workflows in your workspace
Set up regular backups for your data
Consider implementing a CI/CD pipeline for deploying configuration updates
Monitor your VM’s resource usage and scale as needed

For more information on using Oxy, refer to the main documentation.

Learn about deployment

Hands-on Guides

Google Cloud Platform (GCP) Deployment

Deploy Oxy on GCP

Prerequisites

Getting a VM Instance

Pointing Your Domain to the VM (Optional)

Setting Up the VM

Installing Oxy CLI

Setting Up Oxy Workspace

Installing and Configuring Caddy

Setting Up and Starting Oxy as a Service

Optional Configuration and Management

Data Persistence

Managing Your Deployment

Machine Recommendations

Scaling on GCP

Vertical Scaling

Storage Scaling

Troubleshooting

Next Steps

Learn about deployment

Hands-on Guides

​Deploy Oxy on GCP

​Prerequisites

​Getting a VM Instance

​Pointing Your Domain to the VM (Optional)

​Setting Up the VM

​Installing Oxy CLI

​Setting Up Oxy Workspace

​Installing and Configuring Caddy

​Setting Up and Starting Oxy as a Service

​Optional Configuration and Management

​Data Persistence

​Managing Your Deployment

​Machine Recommendations

​Scaling on GCP

​Vertical Scaling

​Storage Scaling

​Troubleshooting

​Next Steps

Deploy Oxy on GCP

Prerequisites

Getting a VM Instance

Pointing Your Domain to the VM (Optional)

Setting Up the VM

Installing Oxy CLI

Setting Up Oxy Workspace

Installing and Configuring Caddy

Setting Up and Starting Oxy as a Service

Optional Configuration and Management

Data Persistence

Managing Your Deployment

Machine Recommendations

Scaling on GCP

Vertical Scaling

Storage Scaling

Troubleshooting

Next Steps