Install GoodData.CN Locally

The GoodData.CN Sandbox is a GitHub repository that provides scripts to automatically deploy a fully functional local instance of GoodData.CN. With a single command, you can spin up all the necessary components in about 15 minutes - perfect for demos, proof-of-concepts, or learning the platform. This installation runs entirely on your machine using Docker and a local Kubernetes cluster.

This automated setup handles the following for you:

• Creates a local Kubernetes cluster using Docker
• Installs GoodData.CN with all required dependencies
• Configures networking, ingress, and access
• Applies demo-friendly defaults

Prerequisites

Before getting started, make sure your machine meets the following requirements:

• Valid GoodData.CN license key
• macOS or Linux operating system
• Docker installed and running
• curl, git, and optionally lsof for port checking
• Ports 80, 5001, and 6443 must be free
• At least 8 GB of RAM and 20 GB of free disk space is recommended

For example, to configure a fresh Debian/Ubuntu machine, run:

# Install required packages
sudo apt update && sudo apt install -y curl git lsof

# Install Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
newgrp docker

# Verify required ports are available (should return blank)
lsof -nP -iTCP:80   -sTCP:LISTEN
lsof -nP -iTCP:5001 -sTCP:LISTEN
lsof -nP -iTCP:6443 -sTCP:LISTEN

Install

1. Clone the GoodData.CN Sandbox repository:

   git clone https://github.com/gooddata/gooddata-cn-local.git
   cd gooddata-cn-local
   

2. Launch the bootstrap container that contains all necessary tools:

   ./shell.sh
   

   This script will:

   • Build or re-attach to an existing bootstrap container
   • Drop you into an interactive shell with pre-installed tools (k3d, kubectl, helm)
   • Mount the necessary volumes for cluster management

3. Inside the bootstrap container, run the setup script:

   ./setup.sh
   

   The setup script will prompt you for:

   • GoodData.CN License Key: Your valid license key
   • Bootstrap User Credentials: Admin username and password for initial access
   • Hostname: The hostname for accessing the UI (defaults to localhost)
   • Optional Docker Credentials: To avoid Docker Hub rate limits during image pulls

   Behind the scenes the script automatically:

   • Creates a K3d cluster named gdcluster
   • Installs the latest GoodData.CN version via Helm
   • Configures ingress and networking
   • Sets up demo-friendly defaults

4. Once installation completes, navigate to your configured hostname (default: http://localhost) and log in with the credentials you provided during setup.

   You can now move onto Getting Started and start testing your local instance of GoodData.CN.

Daily Operations

To return to the bootstrap container shell from your host system, run ./shell.sh (this will either create a new container or re-attach to an existing one).

Use these commands inside the bootstrap container shell:

Upgrade

To upgrade your local installation to a newer version:

1. Check for updates by reviewing the release notes for the latest version and any breaking changes.

2. Modify customized-values-gdcn.yaml for any configuration changes.

3. Run the upgrade by running the following command - replace <RELEASE_VERSION> with the target version (e.g., 3.42.0):

   helm repo update
   GDCN_VERSION=<RELEASE_VERSION>
   helm upgrade --namespace gooddata-cn \
     --version $GDCN_VERSION \
     -f customized-values-gdcn.yaml \
     gooddata-cn gooddata/gooddata-cn
   

Preview Changes

For safer upgrades, preview changes using the Helm Diff plugin:

# Install the diff plugin
helm plugin install https://github.com/databus23/helm-diff

# Preview the upgrade changes
helm repo update
GDCN_VERSION=<RELEASE_VERSION>
helm diff upgrade --color --namespace gooddata-cn \
  --version $GDCN_VERSION \
  -f customized-values-gdcn.yaml \
  gooddata-cn gooddata/gooddata-cn

Troubleshooting

Docker Rate Limits

If you encounter 429 errors during image pulls, the script supports Docker authentication:

• Have your Docker Hub username and password/PAT ready
• The setup script will prompt for these credentials if needed

Port Conflicts

If required ports are in use:

• Stop services using ports 80, 5001, or 6443
• Use lsof -nP -iTCP:<PORT> -sTCP:LISTEN to identify conflicting processes

Cluster Issues

If the cluster fails to start or behaves unexpectedly:

• Delete and recreate: k3d cluster delete gdcluster then run ./setup.sh again
• Check Docker is running and has sufficient resources
• Ensure host ports are available