Containr/docs/developers/onboarding.md

Developer Onboarding Guide

Welcome to the Containr development team! This guide will help you get set up and contribute effectively to the project.

Table of Contents

• Prerequisites
• Development Setup
• Project Structure
• Development Workflow
• Testing
• Code Style
• Debugging
• Contributing
• Resources

Prerequisites

Before you begin, ensure you have the following installed:

Required Tools

• Go 1.24+ - Backend development
• Node.js 18+ - Frontend development
• Docker & Docker Compose - Container development
• Git - Version control
• Make - Build automation

Recommended Tools

• VS Code - Code editor with extensions
• Postman - API testing
• Docker Desktop - Container management
• PostgreSQL Client - Database management

VS Code Extensions

{
  "recommendations": [
    "golang.go",
    "bradlc.vscode-tailwindcss",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-typescript-next",
    "ms-vscode-remote.remote-containers",
    "ms-kubernetes-tools.vscode-kubernetes-tools"
  ]
}

Development Setup

1. Clone the Repository

git clone https://github.com/your-org/containr.git
cd containr

2. Environment Setup

# Copy environment template
cp .env.example .env

# Edit environment variables
nano .env

Key environment variables:

# Development settings
DOMAIN=localhost
ENVIRONMENT=development

# Database
POSTGRES_USER=containr
POSTGRES_PASSWORD=containr
POSTGRES_DB=containr

# Redis
REDIS_PASSWORD=containr

# JWT
JWT_SECRET=your-super-secret-jwt-key-here

# Proxmox (optional)
PROXMOX_BASE_URL=https://your-proxmox:8006
PROXMOX_USERNAME=root@pam
PROXMOX_PASSWORD=your-proxmox-password

3. Initialize Development Environment

# Initialize all services
make init

# Start development mode
make dev

This will start:

• Frontend: http://localhost (React/Vite)
• API: http://api.localhost (Go backend)
• Traefik Dashboard: http://localhost:8080
• Database: PostgreSQL on port 5432
• Redis: Cache on port 6379

4. Verify Setup

# Check service status
make status

# View logs
make logs

# Test API
curl http://api.localhost/health

Project Structure

containr/
├── cmd/                    # Application entry points
│   ├── server/             # Main server application
│   └── cli/               # CLI tool
├── internal/              # Private application code
│   ├── api/              # HTTP handlers and routes
│   ├── build/            # Build system (Nixpacks, Docker)
│   ├── cli/              # CLI commands and utilities
│   ├── config/           # Configuration management
│   ├── database/         # Database operations
│   ├── deployment/       # Deployment engine
│   ├── docker/           # Docker client wrapper
│   ├── metrics/          # Metrics collection
│   ├── middleware/       # HTTP middleware
│   ├── proxmox/         # Proxmox integration
│   ├── scaling/          # Auto-scaling engine
│   └── security/        # Security scanning
├── migrations/           # Database migrations
├── pkg/                 # Public library code
├── scripts/             # Build and utility scripts
├── src/                 # Frontend source code
│   ├── components/       # React components
│   ├── hooks/           # Custom React hooks
│   ├── contexts/        # React contexts
│   └── utils/           # Frontend utilities
├── docs/                # Documentation
├── tests/               # Test files
└── docker-compose.yml   # Development environment

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Your Changes

Backend Changes

• Add new API endpoints in internal/api/
• Update database schema in migrations/
• Add tests in tests/
• Update documentation

Frontend Changes

• Create components in src/components/
• Add hooks in src/hooks/
• Update routing in src/App.tsx
• Follow existing patterns

3. Test Your Changes

# Run backend tests
go test ./...

# Run frontend tests
cd src && npm test

# Test full integration
make up

4. Commit Your Changes

# Stage changes
git add .

# Commit with conventional message
git commit -m "feat: add user authentication"

# Push to your fork
git push origin feature/your-feature-name

5. Create a Pull Request

1. Go to GitHub repository
2. Click "New Pull Request"
3. Select your branch
4. Fill out PR template
5. Request review from team members

Testing

Backend Testing

Unit Tests

# Run all tests
go test ./...

# Run specific package tests
go test ./internal/api

# Run with coverage
go test -cover ./...

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Integration Tests

# Run integration tests
go test -tags=integration ./tests/integration/...

# Test with real database
TEST_DB_URL=postgres://... go test ./tests/integration/...

API Testing

# Start API server
make dev

# Test endpoints
curl http://api.localhost/health
curl -X POST http://api.localhost/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password"}'

Frontend Testing

Unit Tests

cd src
npm test
npm run test:coverage

E2E Tests

cd src
npm run test:e2e

Manual Testing

1. Open http://localhost
2. Test all user flows
3. Check responsive design
4. Verify accessibility

Code Style

Go Backend

Formatting

# Format code
go fmt ./...

# Import organization
goimports -w .

# Lint code
golangci-lint run

Naming Conventions

• Packages: lowercase, snake_case
• Variables: camelCase for local, PascalCase for exported
• Functions: PascalCase for exported, camelCase for private
• Constants: UPPER_SNAKE_CASE
• Files: snake_case.go

Example

package api

import (
    "context"
    "net/http"
)

type UserService struct {
    repo UserRepository
}

func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}
}

func (s *UserService) CreateUser(ctx context.Context, req CreateUserRequest) (*User, error) {
    user := &User{
        Name:  req.Name,
        Email: req.Email,
    }
    
    return s.repo.Create(ctx, user)
}

TypeScript Frontend

Formatting

cd src
npm run format
npm run lint
npm run type-check

Naming Conventions

• Components: PascalCase
• Hooks: camelCase starting with use
• Variables: camelCase
• Constants: UPPER_SNAKE_CASE
• Files: PascalCase.tsx for components, camelCase.ts for utilities

Example

import React, { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';

interface User {
  id: string;
  name: string;
  email: string;
}

export const UserProfile: React.FC<{ userId: string }> = ({ userId }) => {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetchUser(userId).then(setUser).finally(() => setLoading(false));
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <Button onClick={() => console.log('Edit user')}>
        Edit Profile
      </Button>
    </div>
  );
};

Debugging

Backend Debugging

VS Code Debugging

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Backend",
      "type": "go",
      "request": "launch",
      "mode": "auto",
      "program": "${workspaceFolder}/cmd/server",
      "env": {
        "ENVIRONMENT": "development"
      },
      "console": "integratedTerminal"
    }
  ]
}

Logging

import "log"

// Standard logging
log.Printf("Processing user: %s", userID)

// Structured logging (if using logrus/zap)
logger.WithFields(logrus.Fields{
  "user_id": userID,
  "action": "create",
}).Info("User created successfully")

Database Debugging

# Connect to database
make shell-postgres

# View tables
\dt

# Query users
SELECT * FROM users LIMIT 10;

Frontend Debugging

React DevTools

1. Install React DevTools browser extension
2. Open developer tools
3. Inspect component state and props

Network Debugging

// Add request interceptor for debugging
axios.interceptors.request.use(request => {
  console.log('API Request:', request);
  return request;
});

axios.interceptors.response.use(response => {
  console.log('API Response:', response);
  return response;
});

Contributing

Types of Contributions

Bug Fixes

1. Create issue describing the bug
2. Create branch with fix
3. Add tests to prevent regression
4. Submit pull request

Features

1. Create issue for discussion
2. Get approval from maintainers
3. Implement feature with tests
4. Update documentation
5. Submit pull request

Documentation

1. Fix typos and improve clarity
2. Add examples and tutorials
3. Update API documentation
4. Submit pull request

Pull Request Process

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated

Review Guidelines

1. Code Quality: Is the code clean and maintainable?
2. Testing: Are there adequate tests?
3. Documentation: Is the documentation updated?
4. Performance: Will this impact performance?
5. Security: Are there security implications?

Resources

Documentation

• API Documentation
• User Guides
• Architecture Overview

Tools and Links

• Go Documentation
• React Documentation
• Tailwind CSS
• Docker Documentation

Team Communication

• Slack: #containr-dev
• Discord: Development channel
• Email: dev-team@containr.dev

Getting Help

1. Check Documentation: Look for existing solutions
2. Search Issues: Check if problem is already reported
3. Ask in Slack: Get help from team members
4. Create Issue: Report bugs or request features

Development Tips

Productivity Tips

1. Use Make Commands: Leverage make help for available commands
2. Hot Reload: Frontend auto-reloads on file changes
3. Database Migrations: Run make migrate for schema changes
4. Environment Variables: Use .env for local development

Common Issues

1. Port Conflicts: Change ports in .env if needed
2. Permission Issues: Use sudo for Docker commands
3. Dependency Issues: Run go mod tidy and npm install
4. Cache Issues: Clear Docker cache with make clean

Best Practices

1. Small Commits: Keep changes focused and atomic
2. Test Coverage: Aim for >80% coverage
3. Documentation: Document public APIs and complex logic
4. Security: Never commit secrets or sensitive data

Next Steps

Once you're comfortable with the basics:

1. Explore Advanced Features: Learn about scaling, monitoring, and security
2. Contribute to Core: Work on core platform features
3. Mentor Others: Help new developers get started
4. Share Knowledge: Write blog posts or give talks

Welcome aboard! 🚀 We're excited to have you on the team.