Before you start

• You need a Google account (opens in a new tab) with an active GCP billing account

Quick deploy — One click

Click the button below to open Google Cloud Shell with the deployment guide pre-loaded. No manual setup required — Cloud Shell clones the repo and walks you through each step.

(opens in a new tab)

What happens: Cloud Shell opens in your browser, clones the rtSurvey repo, and displays a step-by-step tutorial panel. Each command is clickable — no typing required. Setup takes 5–10 minutes.

Prefer to deploy manually via the GCP Console? Follow the steps below.

Step 1 — Create a GCP account

Go to console.cloud.google.com (opens in a new tab) and sign in with your Google account. Ensure a billing account is linked before proceeding.

Step 2 — Create a project

1. Go to console.cloud.google.com (opens in a new tab)
2. Click the project dropdown at the top → New Project
3. Enter a name (e.g. rtsurvey) → Create
4. Select the new project from the dropdown

Step 3 — Enable Compute Engine API

Go to Compute Engine API (opens in a new tab) → click Enable

Wait about 1 minute for GCP to provision the API.

Step 4 — Create a VM instance

1. Go to Compute Engine → VM instances → Create Instance
2. Fill in the form:

3. Click Advanced options → Management → scroll to Automation
4. Paste the bootstrap snippet below into the Startup script field:

#!/bin/bash
export PROJECT_ID="rtsurvey"
export ADMIN_PASSWORD="admin"
export EMBED_KEYCLOAK="true"
export TZ="Asia/Ho_Chi_Minh"
curl -fsSL https://raw.githubusercontent.com/therealtimex/rtsurvey/main/scripts/gcp-compute.sh | bash

5. Click Create

Customise: Change the export lines to set your own project ID, password, timezone, etc. before clicking Create.

Full script (for review or gcloud CLI upload): gcp-compute.sh (opens in a new tab)

Recommended VM sizes

Step 5 — Open port 3838 (Shiny)

GCP's Allow HTTP/HTTPS checkboxes only open ports 80 and 443. Port 3838 (Shiny analytics) requires a separate rule.

1. Go to VPC network → Firewall → Create firewall rule
2. Fill in the rule:

3. Click Create

Step 6 — Wait for setup to complete

The script runs automatically on first boot. It installs Docker, pulls the rtSurvey image, initialises the database, and starts all services. This takes 5–10 minutes.

No console access needed. Open your browser and go to http://<vm-external-ip>. You will see a loading page while the app finishes starting up. It refreshes automatically every 5 seconds and loads the app once ready.

The VM external IP is shown in the Compute Engine → VM instances list.

To watch the log directly:

ssh <user>@<vm-external-ip>
sudo tail -f /var/log/rtsurvey-setup.log

Step 7 — Set up SSL

Once the app is running, follow the Set Up SSL guide → to configure HTTPS. The free rtsurvey.com subdomain is the fastest option — no DNS setup needed.

Step 8 — Change the default password

All passwords default to admin. Change them immediately after your first login:

• App admin password — account settings inside the app
• Keycloak admin — accessible at https://your-domain.com/auth/admin (login: admin / admin)

Firewall rules (GCP VPC)

The startup script configures ufw inside the VM. You also need these VPC-level firewall rules in GCP:

Inbound

Ports NOT needed externally

Troubleshooting

Check the setup log

sudo tail -200 /var/log/rtsurvey-setup.log

Check the SSL log

sudo tail -200 /var/log/rtsurvey-ssl.log

View container status

docker compose -f /opt/rtsurvey/docker-compose.production.yml ps

Reboot behavior

GCP reruns the startup script on every VM reboot. The script detects an existing installation at /opt/rtsurvey/ and exits immediately — no re-provisioning occurs.