Skip to content

zixiao-labs/GitDock

BranchesTags

Repository files navigation

GitDock - Lightweight GitLab Alternative

GitDock is a lightweight, self-hosted Git repository management platform designed to run efficiently on low-resource environments like AWS t2.micro instances (1vCPU, 1GB RAM). It provides essential features for code hosting, collaboration, and CI/CD.

Features

  • Git Repository Hosting: Full Git repository management with branch operations, commits tracking
  • User Management: JWT-based authentication with RBAC (Owner, Maintainer, Developer, Guest)
  • Issue Tracking: Bug tracking and task management with labels, priorities, and comments
  • CI/CD Pipeline: Automated build, test, and deployment workflows
  • Multi-Database Support: Runtime-switchable PostgreSQL and MSSQL support
  • RESTful API: Complete REST API for all operations
  • Modern Web UI: Vue 3 + MDUI (Material Design 3) frontend with dark mode support
  • High Performance: Core Git operations powered by libgit2 (C library) via CGO
  • Low Resource Usage: Optimized for 1GB RAM environments

Architecture

  • Backend: Go 1.21+ (HTTP server, business logic)
  • Frontend: Vue 3 + MDUI (Material Design 3)
  • Git Engine: C language + libgit2 (via CGO for performance-critical operations)
  • Database: PostgreSQL or MSSQL (runtime configurable)
  • Authentication: JWT tokens with bcrypt password hashing
  • API: RESTful JSON API using Gin framework

Requirements

Runtime

  • Go 1.21 or higher
  • Node.js 18+ (for frontend development)
  • libgit2 (system library)
  • PostgreSQL 12+ or MSSQL Server 2019+
  • 1GB RAM minimum (optimized for AWS t2.micro)
  • 10GB disk space minimum

Build Dependencies

  • GCC or compatible C compiler
  • pkg-config
  • libgit2-dev
  • npm or yarn (for frontend)

Quick Start with Docker

The easiest way to get started is using Docker Compose:

# Clone the repository
git clone https://github.com/yourusername/gitdock.git
cd gitdock

# Start with Docker Compose (includes PostgreSQL)
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f gitdock

The server will be available at http://localhost:8080.

Manual Installation

1. Install Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libgit2-dev

macOS:

brew install libgit2 pkg-config

Alpine Linux:

apk add --no-cache gcc musl-dev libgit2-dev pkgconfig

2. Build the Application

# Clone repository
git clone https://github.com/yourusername/gitdock.git
cd gitdock

# Download Go dependencies
go mod download

# Build (CGO must be enabled for libgit2)
CGO_ENABLED=1 go build -o gitdock ./cmd/server

# Or use Makefile
make build

3. Configure

# Copy example config
cp config.yaml.example config.yaml

# Edit configuration
nano config.yaml

Key Configuration Options:

database:
  type: postgres  # or "mssql"

  postgresql:
    host: localhost
    port: 5432
    user: gitdock
    password: your_password
    database: gitdock
    max_conns: 10  # Optimized for low memory

jwt:
  secret: change-me-in-production
  expiration_hours: 24

git:
  repo_path: ./repositories
  max_repo_size_mb: 500

ci:
  enabled: true
  max_concurrent_jobs: 5

4. Run

# Run directly
./gitdock

# Or with Makefile
make run

# Or in development mode
make dev

Frontend Development

The web UI is built with Vue 3 and MDUI (Material Design 3).

Setup Frontend

# Navigate to web directory
cd web

# Install dependencies
npm install

# Start development server (with API proxy)
npm run dev

The frontend will be available at http://localhost:3000 and will proxy API requests to the backend at http://localhost:8080.

Build Frontend for Production

cd web
npm run build

The built files will be in web/dist/ directory. You can serve them with any static file server or integrate with the Go backend.

For detailed frontend documentation, see web/README.md.

Database Setup

PostgreSQL

# Install PostgreSQL
sudo apt-get install postgresql

# Create database and user
sudo -u postgres psql
CREATE DATABASE gitdock;
CREATE USER gitdock WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE gitdock TO gitdock;
\q

MSSQL

# Using Docker for MSSQL
docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=YourStrong@Password" \
  -p 1433:1433 --name mssql \
  -d mcr.microsoft.com/mssql/server:2022-latest

# Create database (connect with sqlcmd or Azure Data Studio)
CREATE DATABASE gitdock;

API Usage

Register a User

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "admin@example.com",
    "password": "secure_password",
    "full_name": "Admin User"
  }'

Login

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secure_password"
  }'

Response includes JWT token:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { ... }
}

Create Repository

curl -X POST http://localhost:8080/api/v1/repositories \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "description": "My awesome project",
    "is_private": false
  }'

Create Issue

curl -X POST http://localhost:8080/api/v1/issues \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_id": 1,
    "title": "Bug: Login not working",
    "description": "Detailed description",
    "priority": "high",
    "labels": ["bug", "security"]
  }'

Trigger CI/CD Job

curl -X POST http://localhost:8080/api/v1/ci/jobs \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_id": 1,
    "ref": "main",
    "commit_sha": "abc123...",
    "config": "steps:\n  - run: make build\n  - run: make test"
  }'

API Endpoints

Authentication

  • POST /api/v1/auth/register - Register new user
  • POST /api/v1/auth/login - Login and get JWT token

Users

  • GET /api/v1/users/me - Get current user
  • PUT /api/v1/users/me - Update current user
  • GET /api/v1/users - List users
  • GET /api/v1/users/:id - Get user by ID

Repositories

  • POST /api/v1/repositories - Create repository
  • GET /api/v1/repositories - List repositories
  • GET /api/v1/repositories/:id - Get repository
  • PUT /api/v1/repositories/:id - Update repository
  • DELETE /api/v1/repositories/:id - Delete repository
  • GET /api/v1/repositories/:id/branches - List branches
  • POST /api/v1/repositories/:id/branches - Create branch
  • DELETE /api/v1/repositories/:id/branches/:name - Delete branch
  • GET /api/v1/repositories/:id/commits - List commits
  • GET /api/v1/repositories/:id/members - Get members
  • POST /api/v1/repositories/:id/members - Add member

Issues

  • POST /api/v1/issues - Create issue
  • GET /api/v1/issues/:id - Get issue
  • PUT /api/v1/issues/:id - Update issue
  • DELETE /api/v1/issues/:id - Delete issue
  • GET /api/v1/issues/repository/:repo_id - List repository issues
  • POST /api/v1/issues/:id/comments - Create comment
  • GET /api/v1/issues/:id/comments - Get comments

CI/CD

  • POST /api/v1/ci/jobs - Create CI job
  • GET /api/v1/ci/jobs/:id - Get job
  • GET /api/v1/ci/jobs/:id/logs - Get job logs
  • GET /api/v1/ci/repository/:repo_id/jobs - List repository jobs

Deployment on AWS EC2 (t2.micro)

1. Launch EC2 Instance

  • AMI: Ubuntu 22.04 LTS
  • Instance Type: t2.micro (1 vCPU, 1GB RAM)
  • Storage: 10GB gp3

2. Install Dependencies

# Update system
sudo apt-get update && sudo apt-get upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker ubuntu

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

3. Deploy with Docker

# Clone repository
git clone https://github.com/yourusername/gitdock.git
cd gitdock

# Update docker-compose.yml with production settings
# Set strong JWT secret and database passwords

# Start services
docker-compose up -d

# Configure firewall
sudo ufw allow 8080/tcp
sudo ufw enable

4. Setup Reverse Proxy (Optional)

Install Nginx for HTTPS:

sudo apt-get install nginx certbot python3-certbot-nginx

# Configure Nginx
sudo nano /etc/nginx/sites-available/gitdock

# Add configuration:
# server {
#     listen 80;
#     server_name your-domain.com;
#     location / {
#         proxy_pass http://localhost:8080;
#         proxy_set_header Host $host;
#         proxy_set_header X-Real-IP $remote_addr;
#     }
# }

sudo ln -s /etc/nginx/sites-available/gitdock /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# Setup SSL
sudo certbot --nginx -d your-domain.com

Performance Optimization

The application is optimized for 1GB RAM:

  1. Database Connection Pool: Limited to 10 connections
  2. Goroutine Pool: Maximum 50 concurrent operations
  3. Memory Cache: LRU cache with 100MB limit
  4. Streaming: Git objects are processed in streams to minimize memory
  5. Efficient Queries: Indexed database queries with pagination

Project Structure

gitdock/
├── cmd/
│   └── server/          # Main application entry point
├── internal/
│   ├── api/             # HTTP handlers and routing
│   ├── auth/            # Authentication and authorization
│   ├── config/          # Configuration management
│   ├── models/          # Data models
│   └── repository/      # Database abstraction layer
│       ├── postgres/    # PostgreSQL implementation
│       └── mssql/       # MSSQL implementation
├── pkg/
│   └── gitcore/         # C/libgit2 wrapper (CGO)
│       ├── gitcore.h    # C header
│       ├── gitcore.c    # C implementation
│       └── gitcore.go   # Go CGO bindings
├── web/                 # Frontend (Vue 3 + MDUI)
│   ├── src/             # Vue source files
│   │   ├── assets/      # Styles and static files
│   │   ├── components/  # Reusable components
│   │   ├── router/      # Vue Router configuration
│   │   ├── services/    # API services
│   │   ├── stores/      # Pinia state management
│   │   └── views/       # Page components
│   ├── package.json     # Frontend dependencies
│   └── vite.config.js   # Vite configuration
├── config.yaml.example  # Example configuration
├── Dockerfile           # Docker build configuration
├── docker-compose.yml   # Docker Compose setup
├── Makefile            # Build automation
└── README.md           # This file

Development

# Install development dependencies
make install-deps

# Run in development mode (with hot reload)
make dev

# Run tests
make test

# Format code
make fmt

# Lint code
make lint

# Build for production
make build

Limitations

As a lightweight GitLab alternative, GitDock focuses on core features:

  • Basic CI/CD (no complex pipeline visualization)
  • No built-in package registry
  • No wiki or pages hosting
  • Simplified merge request workflow (via Issue system)

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details

Security

  • Always change default JWT secret in production
  • Use strong database passwords
  • Enable SSL/TLS for production deployments
  • Keep dependencies updated
  • Run security audits: go list -json -m all | nancy sleuth

Support

For issues and questions:

Credits

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages