Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Quick Start

1

Clone the repository

git clone https://github.com/benidevo/vega-ai.git
cd vega-ai
2

Set up environment variables

Create a .env file with your configuration:
# Create .env file
cat > .env << EOF
# Required
GEMINI_API_KEY=your-gemini-api-key
TOKEN_SECRET=your-jwt-secret

# Optional - for cloud mode
CLOUD_MODE=false
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
EOF
Generate a secure TOKEN_SECRET using: openssl rand -base64 32
3

Start development environment

Use the Makefile command to build and start the containers:
make run
This command will:
  • Build the Docker image from docker/dev/Dockerfile
  • Start the application container
  • Start the SQLite web dashboard for database inspection
  • Mount your local directory for live code reloading
4

Access the application

Once the containers are running:
The application automatically reloads when you make code changes.

​
Development Commands

The project includes a Makefile with helpful commands:
CommandDescription
make runStart development environment in detached mode
make run-itStart development environment with interactive logs
make restartRebuild and restart containers
make stopStop all containers
make logsView container logs (follows last 100 lines)
make enter-appOpen shell inside app container
make testRun test suite with coverage
make test-verboseRun tests with verbose output
make formatFormat code with gofmt and run go vet

​
Example Usage

# Follow logs in real-time
make logs

​
Frontend Development

​
CSS Build Process

Vega AI uses Tailwind CSS with a build process that optimizes CSS delivery. The production CSS is ~46KB compared to the 340KB CDN version.
1

Install Node.js dependencies

npm install
2

Build CSS for production

npm run build
This generates an optimized static/css/output.css file with only the styles used in your templates.
3

Development with auto-rebuild

For active development, run the watcher:
npm run dev
This watches for changes in your templates and automatically rebuilds the CSS.

​
Template Structure

The frontend is built with Go templates: 
templates/
├── layouts/
│   └── base.html          # Base layout with CSS/JS includes
├── partials/              # Reusable template components
│   ├── header.html
│   ├── footer.html
│   └── ...
└── pages/                 # Page-specific templates

static/
├── css/
│   ├── input.css         # Source Tailwind CSS
│   └── output.css        # Generated (gitignored)
└── js/                   # JavaScript files

​
Project Structure

Understanding the codebase organization: 
vega-ai/
├── cmd/vega/              # Application entry point
├── internal/              # Private application code
│   ├── auth/             # Authentication & authorization
│   ├── job/              # Job management
│   ├── ai/               # AI integration (Gemini)
│   ├── settings/         # User settings & profiles
│   ├── documents/        # Document generation
│   ├── quota/            # Usage quota management
│   └── common/           # Shared utilities
├── templates/            # HTML templates
├── static/              # Static assets
├── migrations/          # Database migrations
│   └── sqlite/         # SQLite migration files
├── docker/              # Docker configurations
│   ├── dev/            # Development Dockerfile
│   └── prod/           # Production Dockerfile
├── scripts/             # Build and utility scripts
└── docs/                # Documentation

​
Key Directories

internal/auth

User authentication, JWT tokens, OAuth integration

internal/job

Job tracking, company management, match results

internal/ai

AI services: CV parsing, job matching, document generation

internal/quota

Usage quota tracking and enforcement for cloud mode

​
Environment Variables

​
Core Application Settings

VariableRequiredDescription
TOKEN_SECRETYesJWT secret for user sessions
GEMINI_API_KEYYesGoogle AI API key
GOOGLE_CLIENT_IDNoGoogle OAuth client ID
GOOGLE_CLIENT_SECRETNoGoogle OAuth client secret

​
Admin User Management

Admin user creation is only available in self-hosted mode. In cloud mode, admin privileges must be granted manually in the database.
VariableRequiredDefaultDescription
ADMIN_USERNAMENoadminAdmin username (3-50 characters)
ADMIN_PASSWORDNoVegaAdminAdmin password (8-64 characters)
RESET_ADMIN_PASSWORDNofalseReset admin password on startup

​
CORS Configuration

VariableRequiredDefaultDescription
CORS_ALLOWED_ORIGINSNo*Comma-separated list of allowed origins
CORS_ALLOW_CREDENTIALSNofalseAllow credentials in CORS requests
# Allow all origins
CORS_ALLOWED_ORIGINS=*
CORS_ALLOW_CREDENTIALS=false

​
Database

Vega AI uses SQLite for data storage:
  • Location: data/vega.db (in Docker volume)
  • Migrations: Automatic on startup
  • Schema: Located in migrations/sqlite/
  • Dashboard: Available at http://localhost:8080 during development

​
Database Commands

CommandDescription
make migrate-createCreate a new migration file
make migrate-upRun pending migrations
make migrate-downRollback last migration
make migrate-resetRollback all migrations
make migrate-forceForce migration to specific version

​
Git Hooks

Set up pre-commit hooks for code quality: 
make setup-hooks
This configures a pre-commit hook that:
  • Checks code formatting with gofmt
  • Runs go vet for static analysis
  • Runs inside Docker containers for consistency

​
Troubleshooting

​
Port Already in Use

If port 8765 is already in use: 
# Find and stop conflicting container
docker ps
docker stop <container-id>

# Or kill the process using the port
lsof -ti:8765 | xargs kill -9

​
Database Locked

If you encounter database lock errors: 
make restart

​
Permission Denied

If you have permission issues with the data directory: 
# Check permissions
ls -la data/

# Fix ownership (if needed)
sudo chown -R $USER:$USER data/

​
Container Won’t Start

View logs to diagnose issues: 
# View all logs
make logs

# View specific container logs
docker compose logs -f app

​
Code Changes Not Reflected

Ensure the volume mount is working: 
# Restart containers
make restart

# Verify volume mount
docker compose exec app ls -la /app

​
Next Steps

Testing Guide

Learn how to write and run tests

Contributing

Contribute to Vega AI development

Build docs developers (and LLMs) love

Get started for freeTalk to us