upctl

upctl is a tool for setting up local development environments using Kubernetes (via Helm) or Docker Compose

• 1. Dependencies
  • 1.1 Software
• 2. Installation
  • 2.1 Install upctl
    • Linux
    • MacOS
• 3. Create a configuration file
  • 3.1 Copy the configuration file and overrides files to home
  • 3.2 Update the configuration file for your environment.
• 4. Login to the teleport server
• 5. Configure repository cache
• 6. Using with Kubernetes (default)
  • 6.1 Install helm packages
  • 6.2 Import database
  • 6.3 Removing packages
• 7. Using with Docker Compose
  • 7.1 Docker Compose Configuration
  • 7.2 Install services with Docker Compose
  • 7.3 Docker Compose Commands
  • 7.4 Import database with Docker Compose

1. Dependencies

1.1 Software

For Kubernetes mode:

• Docker Desktop or colima
• kubectl
• mysql-client
• awscli

For Docker Compose mode:

• Docker Engine
• Docker Compose
• mysql-client (if using database imports)
• awscli (if downloading database dumps from S3)

2. Installation

2.1 Install upctl

Using Homebrew (macOS and Linux)

# Add the tap
brew tap uptime-labs/upctl

# Install upctl
brew install upctl

Manual Installation

Visit the releases page and download the upctl version for your operating system (e.g., Linux, macOS).

Make sure to download the correct version for your operating system.

• upctl_0.x.x_linux_amd64 for Intel-based GNU/Linux
• upctl_0.x.x_linux_arm64 for Arm-based GNU/Linux
• upctl_0.x.x_darwin_amd64 for intel-based macOS
• upctl_0.x.x_darwin_arm64 for Arm-based macOS

Linux

cd ~/Downloads
sudo install -o root -g root -m 0755 upctl_0.8.0_linux_amd64 /usr/local/bin/upctl

MacOS

cd ~/Downloads
chmod +x upctl_0.8.0_darwin_amd64
sudo mv upctl_0.8.0_darwin_amd64 /usr/local/bin/upctl

3. Create a configuration file

3.1 Copy the configuration file and overrides files to home

cp config/upctl.yaml ~/.upctl.yaml
cp -R config/overrides ~/.upctl/

3.2 Update the configuration file for your environment.

The configuration file supports both Kubernetes/Helm and Docker Compose configurations.

repositories:
  - name: grafana
    url: https://grafana.github.io/helm-charts
    username: <username>
    password: <password>

Repository passwords are optional

4. Login to the teleport server

tsh login --proxy=teleport.example.com

5. Configure repository cache

For Kubernetes/Helm mode:

upctl config repo

If you modify repositories, re-run the command to update the repositories cache.

6. Using with Kubernetes (default)

6.1 Install helm packages

upctl install grafana 

To install all packages defined in the configuration:

upctl install --all

6.2 Import database

upctl import-db

6.3 Removing packages

upctl remove <package name>

7. Using with Docker Compose

7.1 Docker Compose Configuration

Add your Docker Compose services to the docker_compose section in your upctl.yaml:

docker_compose:
  version: '3.8'
  services:
    loki:
      image: grafana/loki:latest
      ports:
        - "3100:3100"
      volumes:
        - loki-data:/loki
      command: -config.file=/etc/loki/local-config.yaml
      restart: unless-stopped
      networks:
        - uptimelabs
    
    grafana:
      image: grafana/grafana:latest
      ports:
        - "3000:3000"
      volumes:
        - grafana-data:/var/lib/grafana
      restart: unless-stopped
      networks:
        - uptimelabs
      environment:
        - GF_SECURITY_ADMIN_USER=admin
        - GF_SECURITY_ADMIN_PASSWORD=admin

  volumes:
    loki-data:
      driver: local
    grafana-data:
      driver: local
      
  networks:
    uptimelabs:
      driver: bridge

7.2 Install services with Docker Compose

To install packages using Docker Compose instead of Kubernetes/Helm:

upctl install --docker grafana

To install all Docker Compose services:

upctl install --docker --all

7.3 Docker Compose Commands

Manage your Docker Compose services:

# List available services (defined in your upctl.yaml)
upctl list

# Start a specific service (e.g., grafana)
# A service name is required if --all is not used.
upctl up grafana

# Start all services
upctl up --all

# Stop a specific service (e.g., grafana)
# A service name is required if --all is not used.
# Note: 'docker compose down' itself typically stops all services defined in the compose file.
# Specifying a service name with 'upctl down <service_name>' might be handled by upctl
# to only target specific actions if possible, or the underlying 'docker compose down'
# command might ignore the service name and stop all services.
# Refer to 'upctl down --help' for the most current behavior.
upctl down grafana

# Stop all services
upctl down --all

# View logs for a specific service (e.g., grafana)
# A service name is required if --all is not used.
upctl logs grafana

# View logs for all services
upctl logs --all

7.4 Import database with Docker Compose

Import a database into a Docker MySQL container (ensure the MySQL service is defined in your Docker Compose setup within upctl.yaml):

upctl import-db

Note: The --docker flag for import-db might be legacy if the global context determines Docker Compose usage. Verify with upctl import-db --help. TODO: Clarify if --docker is still needed for import-db or if context implies it.