Grounds Development Infrastructure (grounds-dev) 🚀

A local development infrastructure that provisions a k3d Kubernetes cluster with all necessary components to run the Grounds network.

🎯 Quick Start

# Clone and start everything
git clone <repository-url>
cd grounds-dev
make up

The make up command will automatically install missing prerequisites and deploy:

• k3d Kubernetes cluster (1 server + 2 agents)
• PostgreSQL database in databases namespace
• Agones for game server hosting in games namespace
• Valkey in databases namespace
• Dummy HTTP server for testing in infra namespace
• API namespace for API services and microservices

🔐 Authentication

Docker Hub Authentication

To avoid image pull failures and rate limiting, set your Docker Hub credentials before creating the cluster:

# Set Docker Hub credentials
export DOCKER_USERNAME="your-dockerhub-username"
export DOCKER_PASSWORD="your-dockerhub-token"

安全 Note: Use a Docker Hub access token instead of your password:

1. Go to Docker Hub → Account 设置 → 安全
2. Create a new access token
3. Use the token as DOCKER_PASSWORD

GitHub Container Registry (GHCR) Authentication

To pull private images from GitHub Container Registry, configure your GHCR credentials in the .env file:

# Copy the example file and edit it
cp .env.example .env
# Edit .env and add your credentials

Add the following to your .env file:

GHCR_USERNAME=your-github-username
GHCR_TOKEN=your-github-personal-access-token

Creating a GitHub Personal Access Token (PAT):

1. Go to GitHub → 设置 → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Select the read:packages permission
4. Generate and copy the token
5. Add it to your .env file as GHCR_TOKEN

The bootstrap script automatically:

• Loads credentials from .env file
• Creates a global pull secret (ghcr-pull-secret) in all namespaces
• Configures all default service accounts to use the GHCR pull secret

This enables pulling private GHCR images without specifying imagePullSecrets in your Pod specs.

GitHub 包 (Maven) Authentication

The GitHub token is also required for the self hosted Maven artifacts. Set these properties in ~/.gradle/gradle.properties:

github.user=your-github-username
github.token=your-github-personal-access-token

The Maven repository configuration expects those properties:

maven {
    url = uri("https://maven.pkg.github.com/groundsgg/<repository-name>")
    credentials {
        username = providers.gradleProperty("github.user").get()
        password = providers.gradleProperty("github.token").get()
    }
}

🛠️ Essential Commands

Command	Description
make up	Start complete development environment
make down	Stop and delete the cluster
make reset	Reset the cluster (down + up)
make status	Show cluster and deployment status
make logs	Show logs for all services
make test	Test the deployment
make help	Show all available commands

Development Helpers

Command	Description
make port-forward	Port forward services to localhost

🐛 Quick Troubleshooting

# Check cluster status
kubectl get pods -A

# Check logs
make logs

# Restart everything
make reset

🔒 安全 Note

⚠️ Development only! Default credentials (app/app) are used. Not for production.

License

Licensed under the Apache License, Version 2.0.