Harness Open Source Deployment and Usage Guide

1. Prerequisites

System Requirements

• Go: Version 1.20 or higher
• Node.js: Latest stable version
• Docker: Required for pipeline execution and local development

Development Tools

Install the following Go tools (ensure GOPATH bin directory is in your PATH):

# Install protobuf
brew unlink protobuf
curl -s https://raw.githubusercontent.com/Homebrew/homebrew-core/9de8de7a533609ebfded833480c1f7c05a3448cb/Formula/protobuf.rb > /tmp/protobuf.rb
brew install /tmp/protobuf.rb

# Install protoc-gen-go and protoc-gen-go-grpc
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0

Docker Runtime Configuration

For pipeline execution, configure your Docker runtime:

2. Installation

Clone the Repository

git clone https://github.com/harness/harness.git
cd harness

Install Dependencies

make dep
make tools

3. Configuration

Environment Variables

Create a .local.env file with the following configuration:

# Docker configuration (if using non-default runtime)
# GITNESS_DOCKER_HOST=unix:///Users/<username>/.rd/docker.sock
# GITNESS_DOCKER_API_VERSION=1.45

# Database and storage paths
# Customize as needed

Docker Volume Configuration

For data persistence, configure a bind mount or named volume:

# Recommended: Bind mount
-v /tmp/harness:/data

# Alternative: Named volume
-v harness-data:/data

4. Build & Run

Build the Application

# First, build the user interface
pushd web
yarn install
yarn build
popd

# Then build the Harness binary
make build

Run Locally

# Start the server
./gitness server .local.env

Visit http://localhost:3000 in your browser.

Run with Docker (Production)

docker run -d \
  -p 3000:3000 \
  -p 3022:3022 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/harness:/data \
  --name harness \
  --restart always \
  harness/harness

5. Deployment

Docker Compose

Create a docker-compose.yml for production deployment:

version: '3.8'
services:
  harness:
    image: harness/harness
    ports:
      - "3000:3000"
      - "3022:3022"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - harness-data:/data
    restart: always

volumes:
  harness-data:

Kubernetes Deployment

For Kubernetes deployment, create the following resources:

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: harness
spec:
  replicas: 1
  selector:
    matchLabels:
      app: harness
  template:
    metadata:
      labels:
        app: harness
    spec:
      containers:
      - name: harness
        image: harness/harness
        ports:
        - containerPort: 3000
        - containerPort: 3022
        volumeMounts:
        - name: docker-socket
          mountPath: /var/run/docker.sock
        - name: harness-data
          mountPath: /data
      volumes:
      - name: docker-socket
        hostPath:
          path: /var/run/docker.sock
      - name: harness-data
        persistentVolumeClaim:
          claimName: harness-data

---

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: harness
spec:
  selector:
    app: harness
  ports:
  - port: 3000
    targetPort: 3000
  type: LoadBalancer

---

# pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: harness-data
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

Cloud Platform Deployment

Harness can be deployed on various cloud platforms:

• AWS: Use EC2 with Docker or ECS
• Google Cloud: Deploy on GKE or Compute Engine
• Azure: Use Azure Container Instances or AKS
• Digital Ocean: Deploy on Droplets with Docker

6. Troubleshooting

Common Issues and Solutions

Docker Socket Connection Issues

Problem: Pipeline execution fails with Docker connection errors Solution: Verify Docker socket configuration

# Check if Docker daemon is running
docker ps

# Verify socket location
ls -la /var/run/docker.sock

# For non-standard Docker runtimes, set environment variable
export GITNESS_DOCKER_HOST=unix:///path/to/your/docker.sock

Database Connection Issues

Problem: Application fails to start due to database connection errors Solution: Check volume mounts and permissions

# Verify volume mount
docker volume ls | grep harness

# Check permissions
sudo chown -R 1000:1000 /tmp/harness

Build Failures

Problem: Frontend build fails with missing dependencies Solution: Ensure Node.js and Yarn are properly installed

# Check Node.js version
node --version

# Reinstall dependencies
cd web
rm -rf node_modules
yarn install

API Client Generation Issues

Problem: UI fails to communicate with backend APIs Solution: Regenerate API client code

# Regenerate swagger
./gitness swagger > web/src/services/code/swagger.yaml

# Update services
cd web
yarn services

Pipeline Execution Issues

Problem: Pipelines fail to execute in Docker containers Solution: Check Docker API version compatibility

# Check Docker API version
docker version

# Set specific API version if needed
export GITNESS_DOCKER_API_VERSION=1.45

Registry Conformance Test Failures

Problem: Registry tests fail during development Solution: Run conformance tests with proper configuration

make conformance-test

Memory Issues

Problem: Application crashes due to memory constraints Solution: Increase memory allocation for Docker containers

# For Docker Desktop
# Preferences → Resources → Memory

# For Kubernetes
# Increase resource limits in deployment.yaml

Getting Help

• Documentation: Visit developer.harness.io
• Issues: Report problems on the GitHub Issues
• Community: Join the Harness community for support

Performance Optimization

• Monitor Docker resource usage
• Configure appropriate volume sizes
• Use bind mounts for development, named volumes for production
• Consider horizontal scaling for high-traffic deployments