Git hosting with VeilNet

Prerequisites

• Docker and Docker Compose installed
• VeilNet registration token
• Access to VeilNet Guardian service
• Sufficient disk space for repositories

Overview

This guide shows you how to deploy Gitea, a lightweight, self-hosted Git service, with VeilNet for secure remote access. Gitea provides Git repository hosting, issue tracking, pull requests, and more - similar to GitHub or GitLab.

With VeilNet, you can securely access your Git repositories from anywhere without exposing your server to the public internet.

Step 1: Create Docker Compose Configuration

Create a docker-compose.yml file with the following configuration:

services:
  veilnet-conflux:
    container_name: veilnet-conflux
    restart: unless-stopped
    env_file:
      - .env
    image: veilnet/conflux:beta
    pull_policy: always
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    network_mode: host

  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    restart: unless-stopped
    volumes:
      - gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=sqlite3
    network_mode: "container:veilnet-conflux"
    depends_on:
      - veilnet-conflux

volumes:
  gitea:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./gitea

Step 2: Create Environment File

Create a .env file in the same directory as your docker-compose.yml with the following variables:

VEILNET_REGISTRATION_TOKEN=<YOUR_REGISTRATION_TOKEN>
VEILNET_GUARDIAN=<YOUR_GUARDIAN_URL>
VEILNET_PORTAL=true
VEILNET_CONFLUX_TAG=<YOUR_CONFLUX_TAG>
VEILNET_CONFLUX_CIDR=<VEILNET_CIDR>

Replace the placeholders:

• <YOUR_REGISTRATION_TOKEN>: Your VeilNet registration token (obtained from the VeilNet portal)
• <YOUR_GUARDIAN_URL>: The URL of your VeilNet Guardian service (e.g., https://guardian.veilnet.app)
• <YOUR_CONFLUX_TAG>: A tag to identify this Conflux instance (e.g., git-server)
• <VEILNET_CIDR>: Any IP address (e.g., 10.128.0.5/16) in CIDR format that belongs to the realm subnet (e.g., 10.128.0.0/16)

Step 3: Create Data Directories

Create the directory for persistent data storage:

mkdir -p gitea

This directory will store:

• gitea: Gitea configuration, repositories, and database

Step 4: Deploy the Stack

Start all services:

docker-compose up -d

This will:

• Pull the Gitea and VeilNet Conflux images
• Start both containers
• Create persistent volume for data storage
• Automatically restart containers if they stop

Step 5: Verify Deployment

Check that all containers are running:

docker-compose ps

View the VeilNet Conflux logs to verify it's connecting:

docker logs veilnet-conflux -f

You should see logs indicating successful registration and connection to the VeilNet network.

Step 6: Initial Configuration

Local Access

1. Open http://localhost:3000 in your browser
2. Complete the Gitea installation wizard:
   • Database Type: SQLite3 (default, suitable for small to medium deployments)
   • Site Title: Your organization name
   • Repository Root Path: /data/git/repositories
   • Git LFS Root Path: /data/git/lfs
   • Run As Username: git
   • SSH Server Domain: Use your VeilNet IP (e.g., 10.128.0.5)
   • SSH Port: 2222
   • HTTP Port: 3000
   • Gitea Base URL: http://<veilnet-ip>:3000 (e.g., http://10.128.0.5:3000)
   • Log Path: /data/gitea/log
3. Create your administrator account
4. Click "Install Gitea"

Remote Access via VeilNet

1. Find your host's VeilNet IP address:

ip addr show veilnet

Or check the VeilNet portal to see your assigned IP address.

2. Access Gitea from anywhere using http://<veilnet-ip>:3000 (e.g., http://10.128.0.5:3000)

Step 7: Access Your Git Server

Local Access

Once the service is running, you can access it locally:

• Web UI: http://localhost:3000
• SSH: ssh://git@localhost:2222 (for Git operations)

Remote Access via VeilNet

With VeilNet configured, you can access your Git server remotely from anywhere in the world using the host's VeilNet IP address, as long as your device is also connected to the same VeilNet realm.

Access the web interface using:

• Web UI: http://<veilnet-ip>:3000 (e.g., http://10.128.0.5:3000)
• SSH: ssh://git@<veilnet-ip>:2222 (e.g., ssh://[email protected]:2222)

Step 8: Configure Git Clients

Clone a Repository

# Using HTTPS
git clone http://<veilnet-ip>:3000/username/repo.git

# Using SSH (configure SSH key in Gitea first)
git clone ssh://git@<veilnet-ip>:2222/username/repo.git

Add Remote

# Using HTTPS
git remote add origin http://<veilnet-ip>:3000/username/repo.git

# Using SSH
git remote add origin ssh://git@<veilnet-ip>:2222/username/repo.git

Updating Services

To update to newer versions:

docker-compose pull
docker-compose up -d

This will pull the latest images and restart the containers with updated versions.

Stopping and Removing

To stop all services:

docker-compose down

To remove containers and volumes (this will delete all data):

docker-compose down -v

Warning: Removing volumes will delete all repositories, issues, and user data. Make sure to back up your repositories before removing volumes.

FAQ

Can I use SSH for Git operations?

Yes! Gitea supports SSH for Git operations. Configure your SSH key in Gitea (Settings → SSH / GPG Keys), then use ssh://git@<veilnet-ip>:2222 as your remote URL.

How do I add team members?

1. Add team members to the same VeilNet realm through the VeilNet portal
2. Once they can access Gitea via VeilNet IP, they can create accounts or you can invite them
3. Add them to organizations and repositories as needed
4. Since Gitea shares the network namespace with veilnet-conflux, it can also use the VeilNet TUN device for optimal network performance

Can I use a database other than SQLite?

Yes! You can use PostgreSQL or MySQL by adding a database service to docker-compose.yml and updating the Gitea environment variables. SQLite is fine for small to medium deployments.

How do I back up my repositories?

The gitea directory contains all repositories and data. You can back it up by copying the directory. Gitea also has built-in backup functionality accessible through the admin panel.

Can I use Gitea Actions (CI/CD)?

Yes! Gitea Actions is available in recent versions. You'll need to configure runners, which can also be accessed via VeilNet if deployed on separate hosts.

Why use NET_ADMIN capability instead of privileged mode?

The NET_ADMIN capability provides only the necessary permissions for VeilNet to create and manage network interfaces, without granting full privileged access. This is more secure while still allowing VeilNet to function properly.