Google Cloud Platform (GCP) Deployment
Step-by-step guide for deploying Oxy on Google Cloud Platform
Deploy Oxy on GCP
This guide walks you through deploying Oxy on Google Cloud Platform using Compute Engine VM instances with direct access. We’ll cover everything from setting up a virtual machine to configuring Oxy with proper data persistence.
This guide sets up Oxy for direct access on port 3000. For production deployments, consider implementing additional security measures such as HTTPS with SSL certificates, authentication, and network access controls.
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)
- For optimal cost-performance, consider using ARM-based instances (T2A series):
- Boot disk:
- Operating System: Ubuntu
- Version: Latest stable (e.g., Ubuntu 22.04)
- Size: recommended starting point 10 GB
- Firewall:
- Check “Allow HTTP traffic” to allow access on port 3000
- You may also check “Allow HTTPS traffic” if you plan to set up HTTPS later
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)
- Host/Name:
- 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)
- Host/Name:
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:
Update System and Install Essential Packages
Installing Oxy CLI
Let’s install Oxy directly on the VM:
Install Required Dependencies
Install Oxy
Run the official Oxy installation script:
This script will download and install the latest stable version of Oxy.
Verify the Installation
Confirm that Oxy is installed correctly:
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
Initialize Oxy Project
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
andworkflows
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:
Then clone your existing repository:
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
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:
Add your environment variables:
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.
Firewall Configuration
To ensure your Oxy deployment is accessible, you need to create a firewall rule that allows traffic on port 3000:
Create Firewall Rule
In the Google Cloud Console, navigate to VPC network > Firewall.
Create Rule for Port 3000
Click CREATE FIREWALL RULE and configure:
- Name:
allow-oxy-port-3000
- Direction: Ingress
- Action: Allow
- Targets: Specified target tags
- Target tags:
oxy-server
(or the tag you want to use) - Source IP ranges:
0.0.0.0/0
(for public access) or your specific IP range for restricted access - Protocols and ports:
- Check “Specified protocols and ports”
- Select “TCP”
- Enter port
3000
Click CREATE to save the rule.
Apply Tag to Your VM
Go back to Compute Engine > VM instances, select your VM instance, and click EDIT.
In the Network tags field, add oxy-server
(or whatever tag you used in the firewall rule).
Click SAVE.
Opening port 3000 to 0.0.0.0/0 allows public access to your Oxy instance. For production deployments, consider restricting access to specific IP ranges or implementing additional authentication measures.
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
Add the following content:
We specify port 3000 explicitly to match the firewall rule configuration. The service will be accessible directly on this port from the internet.
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
Verify the Service
You should see that the service is active and running.
View Logs (if needed)
If you encounter any issues, check the logs:
This command will show you the live logs from the Oxy service.
Test the Connection
You can test if Oxy is responding properly:
You should get a positive response indicating that Oxy is running.
Access Your Deployment
You can now access your Oxy deployment using:
If you’ve configured a domain name:
Or directly using your VM’s external IP:
For production deployments with HTTPS, consider setting up a reverse proxy like nginx with Let’s Encrypt certificates, or implementing additional GCP services for SSL termination and enhanced security.
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 Service
If you need to stop the Oxy service temporarily:
Updating Oxy
To update Oxy to the latest version:
Backup Data
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 service:
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:
-
To make the mount persistent across reboots, add it to fstab:
Troubleshooting
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.