Deploying a Gitness App

Introduction

Gitness is a powerful open-source development platform that provides integrated source control (Git), CI/CD pipelines, and container registry capabilities all in one unified solution. Built by Harness, Gitness offers developers a self-hosted alternative to platforms like GitLab and GitHub, with a focus on simplicity and performance. This comprehensive guide demonstrates how to deploy Gitness on Klutch.sh using a Dockerfile, covering everything from initial setup to production configuration with persistent storage, environment variables, and security best practices.

Whether you’re setting up a private code repository for your team, building automated CI/CD pipelines, or managing container images, Gitness provides the tools you need. Deploying on Klutch.sh gives you a managed infrastructure with automatic scaling, secure HTTPS endpoints, and persistent volume support to ensure your code and configuration are never lost.

Prerequisites

A Klutch.sh account
A GitHub repository for your Gitness deployment configuration
Basic familiarity with Docker, Git, and environment variables
(Optional) PostgreSQL database for production deployments (SQLite works for testing)
Understanding of persistent storage for code repositories and build artifacts

Project Structure

A minimal repository layout for deploying Gitness on Klutch.sh:

gitness-deploy/
├─ Dockerfile
├─ docker-entrypoint.sh
├─ .gitignore
└─ README.md

This structure keeps your deployment configuration version-controlled and reproducible.

1) Dockerfile for Gitness

Gitness provides an official Docker image that we’ll use as the base. Here’s a production-ready Dockerfile:

FROM harness/gitness:latest

# Set working directory
WORKDIR /data

# Expose Gitness HTTP port
EXPOSE 3000

# Create data directory for persistence
RUN mkdir -p /data

# Default command will start Gitness server
CMD ["gitness", "server"]

For a more customized setup with specific version pinning:

FROM harness/gitness:3.0.0

# Install additional tools if needed
USER root
RUN apk add --no-cache \
    git \
    openssh-client \
    ca-certificates

# Set up directory structure
RUN mkdir -p /data/repos /data/config /data/logs

# Switch back to gitness user for security
USER gitness

WORKDIR /data

EXPOSE 3000

# Health check to ensure service is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/healthz || exit 1

CMD ["gitness", "server"]

2) Environment Variables

Configure these environment variables in your Klutch.sh dashboard under the app settings:

Basic Configuration

# Server configuration
GITNESS_HTTP_PORT=3000
GITNESS_URL_BASE=https://example-app.klutch.sh

# Database configuration (SQLite for testing)
GITNESS_DATABASE_DRIVER=sqlite
GITNESS_DATABASE_DATASOURCE=/data/gitness.db

# Security
GITNESS_TOKEN_SECRET=your-random-secret-key-here
GITNESS_ADMIN_PASSWORD=strong-admin-password

Production Configuration with PostgreSQL

For production deployments, use PostgreSQL instead of SQLite:

# Server configuration
GITNESS_HTTP_PORT=3000
GITNESS_URL_BASE=https://git.yourdomain.com

# PostgreSQL database
GITNESS_DATABASE_DRIVER=postgres
GITNESS_DATABASE_DATASOURCE=postgres://user:password@postgres-host:5432/gitness?sslmode=disable

# Security and secrets
GITNESS_TOKEN_SECRET=generate-a-secure-random-string
GITNESS_ADMIN_PASSWORD=secure-admin-password-here
GITNESS_ADMIN_EMAIL=admin@yourdomain.com

# Git configuration
GITNESS_GIT_HOOK_PATH=/data/hooks
GITNESS_GIT_ROOT=/data/repos

# Logging
GITNESS_LOG_LEVEL=info

Important Security Notes:

Always use strong, randomly generated values for GITNESS_TOKEN_SECRET
Store sensitive values as secrets in Klutch.sh dashboard
Never commit passwords or tokens to your Git repository
Rotate secrets regularly in production environments

3) Persistent Storage Configuration

Gitness requires persistent storage for Git repositories, database files, and configuration. Configure volumes in your Klutch.sh dashboard:

Volume Mount Paths

Primary Data Volume: Mount a persistent volume to /data

Size: Minimum 10GB, recommend 50GB+ for production
This stores: Git repositories, SQLite database (if used), logs, and configuration

Repository Storage: If using separate volume for repositories: /data/repos

Size: Based on expected repository sizes, recommend 100GB+ for active development
Stores all Git repository data

Build Artifacts (optional): /data/artifacts

Size: 20GB+ depending on CI/CD usage
Stores pipeline artifacts and cache

Setting Up Volumes on Klutch.sh

Navigate to your app in the Klutch.sh dashboard

In the app settings, locate the “Volumes” section

Click “Add Volume” and configure:

Mount Path: /data
Size: 50GB (adjust based on needs)

Save the volume configuration

Volume Best Practices:

Start with at least 10GB and monitor usage
Set up monitoring alerts for disk usage
Plan for growth — repository data increases over time
Regular backups of the /data volume are essential

4) Deploying to Klutch.sh

Follow these steps to deploy Gitness on Klutch.sh:

Prepare Your Repository

# Create a new repository
mkdir gitness-deploy
cd gitness-deploy

# Create Dockerfile
cat > Dockerfile << 'EOF'
FROM harness/gitness:latest
WORKDIR /data
RUN mkdir -p /data
EXPOSE 3000
CMD ["gitness", "server"]
EOF

# Initialize git and push to GitHub
git init
git add Dockerfile
git commit -m "Add Gitness Dockerfile"
git remote add origin https://github.com/yourusername/gitness-deploy.git
git push -u origin main

Create App in Klutch.sh

Log in to the Klutch.sh dashboard
Click “Create New App”
Select your GitHub repository containing the Dockerfile
Choose the branch (typically main or master)

Configure Build Settings

Klutch.sh will automatically detect your Dockerfile
No additional build configuration needed

Set Container Port

In the networking section, specify the internal port: 3000
Select traffic type: HTTP (Gitness serves web traffic)

Add Environment Variables

Navigate to the “Environment Variables” section
Add the variables from section 2 above
Mark sensitive variables (passwords, secrets) as “Secret”

Attach Persistent Volume

In the “Volumes” section, add a new volume
Mount path: /data
Size: 50GB (minimum)

Deploy the Application

Review all settings
Click “Deploy”
Klutch.sh will build the Docker image and start your container

Access Your Gitness Instance

Once deployed, access via the provided URL: https://example-app.klutch.sh
Complete the initial setup wizard
Create your admin account using the credentials from environment variables

5) Initial Setup and Configuration

After deployment, complete the Gitness setup:

Access the Web Interface

Navigate to your app URL: https://example-app.klutch.sh
You should see the Gitness login page

Initial Admin Setup

Log in with the admin credentials set in environment variables
If this is first run, you may need to complete the setup wizard

Configure Git Settings

Go to Settings → Git Configuration
Set your Git username and email
Configure SSH keys if using SSH for Git operations

Create Your First Repository

Click “New Repository”
Enter repository name and description
Choose visibility (public or private)
Initialize with README if desired

Test Repository Access

# Clone your new repository
git clone https://example-app.klutch.sh/username/repository.git

# Add some files
cd repository
echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git push origin main

6) Sample Code and Getting Started

Creating Your First Pipeline

Gitness includes built-in CI/CD capabilities. Here’s a sample pipeline configuration (.gitness.yml):

version: 1

pipelines:
  - name: build-and-test
    stages:
      - name: build
        steps:
          - name: build-app
            type: run
            spec:
              container: node:18-alpine
              script: |
                npm install
                npm run build

      - name: test
        steps:
          - name: run-tests
            type: run
            spec:
              container: node:18-alpine
              script: |
                npm test

      - name: deploy
        when:
          branch:
            - main
        steps:
          - name: deploy-to-prod
            type: run
            spec:
              container: alpine:latest
              script: |
                echo "Deploying to production..."
                # Add your deployment commands here

Sample Webhook Configuration

Configure webhooks to trigger external services:

# Using curl to create a webhook
curl -X POST https://example-app.klutch.sh/api/v1/repos/{owner}/{repo}/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-webhook",
    "url": "https://your-service.com/webhook",
    "events": ["push", "pull_request"],
    "active": true
  }'

Using Gitness API

Gitness provides a RESTful API for automation:

// Example: Fetch repositories using Node.js
const axios = require('axios');

const gitnessUrl = 'https://example-app.klutch.sh';
const token = 'your-api-token';

async function listRepositories() {
  try {
    const response = await axios.get(`${gitnessUrl}/api/v1/repos`, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    console.log('Repositories:', response.data);
  } catch (error) {
    console.error('Error fetching repositories:', error.message);
  }
}

listRepositories();

Git Command Examples

# Clone a repository
git clone https://example-app.klutch.sh/username/my-project.git

# Add Gitness as a remote to existing project
git remote add gitness https://example-app.klutch.sh/username/my-project.git
git push gitness main

# Configure git credentials for Gitness
git config --global credential.helper store
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

7) Custom Domain Configuration

To use your own domain with Gitness:

Add Custom Domain in Klutch.sh

Navigate to your app settings
Go to “Domains” section
Click “Add Custom Domain”
Enter your domain: git.yourdomain.com

Configure DNS

Add a CNAME record in your DNS provider:

git.yourdomain.com → example-app.klutch.sh

Or use an A record if provided by Klutch.sh

Update Gitness Configuration

Update the GITNESS_URL_BASE environment variable:
Terminal window
```
GITNESS_URL_BASE=https://git.yourdomain.com
```
Redeploy the app for changes to take effect

Verify SSL Certificate

Klutch.sh automatically provisions SSL certificates
Access your custom domain to verify HTTPS works

8) Database Setup and Migration

Using PostgreSQL for Production

For production environments, PostgreSQL is recommended over SQLite:

Provision PostgreSQL Database

Deploy a PostgreSQL instance on Klutch.sh or use external provider
Note the connection details: host, port, username, password, database name

Update Environment Variables

GITNESS_DATABASE_DRIVER=postgres
GITNESS_DATABASE_DATASOURCE=postgres://username:password@host:5432/gitness?sslmode=require

Database Migration

Gitness automatically handles schema migrations on startup
First run will initialize the database schema
Subsequent runs will migrate as needed

Backup Configuration

Set up regular PostgreSQL backups

Use pg_dump for manual backups:

pg_dump -h postgres-host -U username -d gitness > gitness-backup.sql

Migrating from SQLite to PostgreSQL

If you started with SQLite and want to migrate:

# Export from SQLite (if tools are available)
sqlite3 /data/gitness.db .dump > gitness-export.sql

# Import to PostgreSQL
psql -h postgres-host -U username -d gitness < gitness-export.sql

Note: Migration may require data transformation. Test thoroughly before production migration.

9) Networking and Port Configuration

Gitness uses HTTP traffic on port 3000 by default:

Internal Port Configuration

When configuring your app in Klutch.sh:

Internal Port: 3000 (the port Gitness listens on inside the container)
Traffic Type: Select “HTTP” in the Klutch.sh dashboard

SSH Git Access (Optional)

For SSH-based Git operations:

Configure SSH Port in Gitness

GITNESS_SSH_PORT=2222

Update Dockerfile to Expose SSH Port

FROM harness/gitness:latest
WORKDIR /data
EXPOSE 3000 2222
CMD ["gitness", "server"]

Configure TCP Traffic in Klutch.sh

For SSH access, you’ll need TCP traffic
In the Klutch.sh dashboard, navigate to your app’s networking settings
Select traffic type: “TCP”
External port: Users connect to port 8000
Internal port: Set to 2222 (where Gitness SSH listens in the container)
This creates a mapping where external connections to port 8000 are routed to the container’s internal port 2222

Client Configuration

# Configure SSH to use custom port
git clone ssh://git@example-app.klutch.sh:8000/username/repo.git

10) Security Best Practices

Authentication and Access Control

Strong Admin Credentials

Use complex passwords for admin account
Store credentials securely in password manager
Rotate passwords regularly

Enable Two-Factor Authentication

Configure 2FA in user settings
Require 2FA for admin accounts

API Token Management

Generate API tokens with minimal required permissions
Set expiration dates for tokens
Rotate tokens regularly
Never commit tokens to repositories

User Access Control

Create users with appropriate permissions
Use teams and organizations for access management
Regularly audit user access

Network Security

# Use HTTPS only
GITNESS_URL_BASE=https://git.yourdomain.com

# If using PostgreSQL, enable SSL
GITNESS_DATABASE_DATASOURCE=postgres://user:pass@host:5432/gitness?sslmode=require

Container Security

Keep the Gitness image updated to latest stable version
Regularly scan for vulnerabilities
Use read-only root filesystem where possible
Run as non-root user (Gitness image handles this)

11) Monitoring and Maintenance

Health Checks

Gitness provides health check endpoints:

# Check service health
curl https://example-app.klutch.sh/healthz

# Check database connectivity
curl https://example-app.klutch.sh/api/v1/system/health

Logging

Access logs through Klutch.sh dashboard or configure external logging:

# Set log level
GITNESS_LOG_LEVEL=debug  # Use 'info' for production

# Log format
GITNESS_LOG_FORMAT=json

Monitoring Metrics

Key metrics to monitor:

Disk usage on /data volume
Database connection pool status
API response times
Git operation latency
Pipeline execution times

Backup Strategy

Regular Volume Backups

Back up the /data volume daily
Retain backups for 30+ days
Test restore procedures regularly

Database Backups

For PostgreSQL: automated daily backups
For SQLite: backup /data/gitness.db file

Repository Mirrors

Consider mirroring critical repositories to external Git service
Automated backup jobs can push to backup remote

12) Troubleshooting

Common Issues and Solutions

Issue: Cannot access Gitness web interface

Check if container is running:

# View logs in Klutch.sh dashboard

Verify environment variables are set correctly:

Ensure GITNESS_HTTP_PORT=3000
Check GITNESS_URL_BASE matches your domain

Confirm port configuration:

Internal port should be 3000
Traffic type should be HTTP

Issue: Git push fails with authentication error

Verify credentials:

git credential reject
# Then try push again with correct credentials

Check user permissions in Gitness dashboard

Generate new personal access token if needed

Issue: Database connection errors

Verify database credentials in environment variables

Check network connectivity between Gitness and database:

# If both Gitness and PostgreSQL are deployed on Klutch.sh,
# they can communicate using internal networking if in the same project
# Use the PostgreSQL app's internal hostname (e.g., postgres-app-name.internal)
# Refer to Klutch.sh networking documentation for service discovery

Review database logs for connection issues

Verify database exists and user has proper permissions

Issue: Disk space errors

Check volume usage in Klutch.sh dashboard

Increase volume size if needed

Clean up old pipeline artifacts:

# Access container and run
du -sh /data/*
# Remove unnecessary files

Issue: Pipeline fails to execute

Check pipeline syntax in .gitness.yml

Review pipeline logs in Gitness UI

Verify container images are accessible

Check environment variables required by pipeline steps

13) Scaling and Performance

Vertical Scaling

For larger teams or repositories:

Increase instance size in Klutch.sh dashboard:

Navigate to your app settings
Go to the “Resources” or “Instance” section
Select a larger instance type with more CPU and memory
Recommended for production: 2+ CPU cores, 4GB+ RAM

Adjust storage:

Increase volume size as repositories grow
Monitor disk usage regularly
Plan capacity based on repository growth rate

Database Optimization

# For PostgreSQL, enable connection pooling
GITNESS_DATABASE_DATASOURCE=postgres://user:pass@host:5432/gitness?sslmode=require&pool_max_conns=20

# Set appropriate cache sizes
GITNESS_CACHE_SIZE=1000

Performance Tuning

# Adjust Git performance settings
GITNESS_GIT_CACHE_SIZE=512MB
GITNESS_GIT_MAX_CONNECTIONS=100

# Pipeline concurrency
GITNESS_PIPELINE_MAX_WORKERS=10

14) Integration Examples

Integrate with Slack

# Add webhook in Gitness for Slack notifications
curl -X POST https://example-app.klutch.sh/api/v1/repos/{owner}/{repo}/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
    "events": ["push", "pull_request", "pipeline"]
  }'

Integrate with Existing CI/CD

# Trigger external CI/CD on Gitness events
version: 1

pipelines:
  - name: trigger-external-ci
    stages:
      - name: notify
        steps:
          - name: webhook
            type: run
            spec:
              container: curlimages/curl:latest
              script: |
                curl -X POST https://ci.example.com/trigger \
                  -d '{"repo": "$GITNESS_REPO", "sha": "$GITNESS_COMMIT"}'

15) Upgrading Gitness

To upgrade to a new version of Gitness:

Update Dockerfile

FROM harness/gitness:3.1.0  # Update to new version
WORKDIR /data
EXPOSE 3000
CMD ["gitness", "server"]

Commit and Push Changes

git add Dockerfile
git commit -m "Upgrade Gitness to v3.1.0"
git push origin main

Deploy Update in Klutch.sh

Klutch.sh will automatically rebuild with new image
Or trigger manual deploy from dashboard

Verify Upgrade

Check version in Gitness UI
Test key functionality
Review logs for any migration issues

Backup Before Upgrading

Always backup data before major version upgrades
Test upgrade in staging environment first

16) Advanced Configuration

Custom Git Hooks

# Configure custom Git hooks
GITNESS_GIT_HOOK_PATH=/data/hooks

# Create hook scripts in volume
# /data/hooks/pre-receive
# /data/hooks/post-receive

LDAP Integration

# Configure LDAP authentication
GITNESS_AUTH_LDAP_ENABLED=true
GITNESS_AUTH_LDAP_HOST=ldap.example.com
GITNESS_AUTH_LDAP_PORT=389
GITNESS_AUTH_LDAP_BASE_DN=dc=example,dc=com
GITNESS_AUTH_LDAP_BIND_DN=cn=admin,dc=example,dc=com
GITNESS_AUTH_LDAP_BIND_PASSWORD=secret

OAuth Integration

# Configure OAuth provider (GitHub, GitLab, etc.)
GITNESS_OAUTH_ENABLED=true
GITNESS_OAUTH_PROVIDER=github
GITNESS_OAUTH_CLIENT_ID=your-client-id
GITNESS_OAUTH_CLIENT_SECRET=your-client-secret

Resources

Conclusion

Deploying Gitness on Klutch.sh provides a powerful, self-hosted development platform with integrated Git hosting, CI/CD pipelines, and container registry capabilities. With proper configuration of persistent storage, environment variables, and security settings, you can create a production-ready environment for your development team. The combination of Gitness’s comprehensive features and Klutch.sh’s managed infrastructure ensures reliable, scalable, and secure code management and continuous integration workflows.

For additional help, consult the Klutch.sh documentation or reach out to the community forums for support.