mirror of
https://github.com/Dvorinka/Containr.git
synced 2026-06-03 20:12:58 +00:00
feat: initial implementation of container management platform
This commit is contained in:
Tomas Dvorak
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,553 @@
|
||||
# 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](#prerequisites)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Development Workflow](#development-workflow)
|
||||
- [Testing](#testing)
|
||||
- [Code Style](#code-style)
|
||||
- [Debugging](#debugging)
|
||||
- [Contributing](#contributing)
|
||||
- [Resources](#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
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-org/containr.git
|
||||
cd containr
|
||||
```
|
||||
|
||||
### 2. Environment Setup
|
||||
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit environment variables
|
||||
nano .env
|
||||
```
|
||||
|
||||
Key environment variables:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# Run backend tests
|
||||
go test ./...
|
||||
|
||||
# Run frontend tests
|
||||
cd src && npm test
|
||||
|
||||
# Test full integration
|
||||
make up
|
||||
```
|
||||
|
||||
### 4. Commit Your Changes
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Run integration tests
|
||||
go test -tags=integration ./tests/integration/...
|
||||
|
||||
# Test with real database
|
||||
TEST_DB_URL=postgres://... go test ./tests/integration/...
|
||||
```
|
||||
|
||||
#### API Testing
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
cd src
|
||||
npm test
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
#### E2E Tests
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```go
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```tsx
|
||||
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`:
|
||||
```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
|
||||
```go
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```tsx
|
||||
// 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
|
||||
```markdown
|
||||
## 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](../api/openapi.yaml)
|
||||
- [User Guides](../guides/)
|
||||
- [Architecture Overview](../../README.md)
|
||||
|
||||
### Tools and Links
|
||||
- [Go Documentation](https://golang.org/doc/)
|
||||
- [React Documentation](https://react.dev/)
|
||||
- [Tailwind CSS](https://tailwindcss.com/)
|
||||
- [Docker Documentation](https://docs.docker.com/)
|
||||
|
||||
### 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.
|
||||
@@ -0,0 +1,627 @@
|
||||
# Advanced Configuration Guide
|
||||
|
||||
This guide covers advanced configuration options for optimizing your Containr deployments.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Build Configuration](#build-configuration)
|
||||
- [Environment Management](#environment-management)
|
||||
- [Resource Allocation](#resource-allocation)
|
||||
- [Networking](#networking)
|
||||
- [Security](#security)
|
||||
- [Scaling Policies](#scaling-policies)
|
||||
- [Custom Domains and SSL](#custom-domains-and-ssl)
|
||||
- [Health Checks](#health-checks)
|
||||
|
||||
## Build Configuration
|
||||
|
||||
### Nixpacks Configuration
|
||||
|
||||
Nixpacks is the default build system. You can customize it using a `nixpacks.toml` file:
|
||||
|
||||
```toml
|
||||
# nixpacks.toml
|
||||
[phases.setup]
|
||||
nixPkgs = ["...", "nodejs", "npm"]
|
||||
|
||||
[phases.build]
|
||||
cmds = ["npm run build"]
|
||||
|
||||
[start]
|
||||
cmd = "npm start"
|
||||
|
||||
[variables]
|
||||
NODE_ENV = "production"
|
||||
PORT = "8080"
|
||||
```
|
||||
|
||||
### Custom Dockerfile
|
||||
|
||||
For complex applications, use a custom Dockerfile:
|
||||
|
||||
```dockerfile
|
||||
# Dockerfile
|
||||
FROM node:18-alpine AS builder
|
||||
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production
|
||||
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM node:18-alpine AS runtime
|
||||
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/dist ./dist
|
||||
COPY --from=builder /app/node_modules ./node_modules
|
||||
COPY package*.json ./
|
||||
|
||||
EXPOSE 8080
|
||||
USER node
|
||||
CMD ["npm", "start"]
|
||||
```
|
||||
|
||||
### Build Caching
|
||||
|
||||
Enable build caching for faster deployments:
|
||||
|
||||
1. Go to service settings
|
||||
2. Enable "Build Caching"
|
||||
3. Configure cache settings:
|
||||
- **Cache TTL**: Time to keep cached layers (default: 7 days)
|
||||
- **Max Cache Size**: Maximum cache size per service
|
||||
|
||||
### Multi-Stage Builds
|
||||
|
||||
Optimize image size with multi-stage builds:
|
||||
|
||||
```dockerfile
|
||||
# Build stage
|
||||
FROM golang:1.21 AS builder
|
||||
WORKDIR /app
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN CGO_ENABLED=0 go build -o app
|
||||
|
||||
# Runtime stage
|
||||
FROM alpine:latest
|
||||
RUN apk --no-cache add ca-certificates
|
||||
WORKDIR /root/
|
||||
COPY --from=builder /app/app .
|
||||
EXPOSE 8080
|
||||
CMD ["./app"]
|
||||
```
|
||||
|
||||
## Environment Management
|
||||
|
||||
### Environment Scopes
|
||||
|
||||
Variables can be scoped at different levels:
|
||||
|
||||
```bash
|
||||
# Project-level (shared across all services)
|
||||
DATABASE_URL=postgresql://...
|
||||
|
||||
# Service-level (specific to one service)
|
||||
API_KEY=service-specific-key
|
||||
|
||||
# Environment-specific (production only)
|
||||
NODE_ENV=production
|
||||
DEBUG=false
|
||||
```
|
||||
|
||||
### Variable Types
|
||||
|
||||
#### Plain Text Variables
|
||||
```bash
|
||||
API_KEY=your-api-key-here
|
||||
```
|
||||
|
||||
#### Secret Variables
|
||||
```bash
|
||||
# Marked as secret in UI - masked in logs
|
||||
DATABASE_PASSWORD=super-secret-password
|
||||
```
|
||||
|
||||
#### File Variables
|
||||
For configuration files:
|
||||
```bash
|
||||
# Upload .env file as variable
|
||||
ENV_FILE_CONTENT=KEY1=value1\nKEY2=value2
|
||||
```
|
||||
|
||||
### Dynamic Variables
|
||||
|
||||
Use Containr's built-in variables:
|
||||
|
||||
```bash
|
||||
# Auto-populated by Containr
|
||||
PORT=8080 # Assigned port
|
||||
CONTAINR_SERVICE_NAME=my-app # Service name
|
||||
CONTAINR_PROJECT_NAME=my-proj # Project name
|
||||
CONTAINR_DEPLOYMENT_ID=abc123 # Deployment ID
|
||||
```
|
||||
|
||||
## Resource Allocation
|
||||
|
||||
### CPU Allocation
|
||||
|
||||
Configure CPU limits and requests:
|
||||
|
||||
```yaml
|
||||
# Service resource configuration
|
||||
resources:
|
||||
cpu:
|
||||
request: "100m" # Minimum CPU (0.1 core)
|
||||
limit: "1000m" # Maximum CPU (1 core)
|
||||
memory:
|
||||
request: "128Mi" # Minimum memory
|
||||
limit: "512Mi" # Maximum memory
|
||||
```
|
||||
|
||||
### Memory Allocation
|
||||
|
||||
Memory configuration examples:
|
||||
|
||||
```yaml
|
||||
# Small service (API, worker)
|
||||
resources:
|
||||
memory: "256Mi"
|
||||
|
||||
# Medium service (web app)
|
||||
resources:
|
||||
memory: "512Mi"
|
||||
|
||||
# Large service (database, analytics)
|
||||
resources:
|
||||
memory: "2Gi"
|
||||
```
|
||||
|
||||
### Storage Allocation
|
||||
|
||||
Persistent storage for databases:
|
||||
|
||||
```yaml
|
||||
# Database service
|
||||
resources:
|
||||
storage:
|
||||
size: "10Gi"
|
||||
type: "ssd"
|
||||
backup: true
|
||||
```
|
||||
|
||||
## Networking
|
||||
|
||||
### Service-to-Service Communication
|
||||
|
||||
Services can communicate internally:
|
||||
|
||||
```bash
|
||||
# Environment variables for internal URLs
|
||||
DATABASE_URL=postgresql://my-db:5432/myapp
|
||||
REDIS_URL=redis://my-redis:6379
|
||||
API_URL=http://my-api:8080
|
||||
```
|
||||
|
||||
### Port Configuration
|
||||
|
||||
Configure service ports:
|
||||
|
||||
```yaml
|
||||
# Service configuration
|
||||
networking:
|
||||
port: 8080 # Internal port
|
||||
public: true # Expose publicly
|
||||
health_check: "/health" # Health check endpoint
|
||||
```
|
||||
|
||||
### Custom Domains
|
||||
|
||||
Set up custom domains:
|
||||
|
||||
1. Go to service settings → "Domains"
|
||||
2. Add your domain: `app.yourdomain.com`
|
||||
3. Configure DNS:
|
||||
```
|
||||
CNAME app.yourdomain.com -> your-service.containr.app
|
||||
```
|
||||
4. Wait for SSL certificate provisioning
|
||||
|
||||
### Load Balancing
|
||||
|
||||
Configure load balancing strategies:
|
||||
|
||||
```yaml
|
||||
# Load balancer configuration
|
||||
load_balancer:
|
||||
strategy: "round_robin" # round_robin, least_connections, ip_hash
|
||||
health_check:
|
||||
path: "/health"
|
||||
interval: "30s"
|
||||
timeout: "5s"
|
||||
retries: 3
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
### Security Scans
|
||||
|
||||
Enable automated security scanning:
|
||||
|
||||
1. Go to project settings → "Security"
|
||||
2. Enable "Security Scanning"
|
||||
3. Configure scan frequency:
|
||||
- **On every deployment**
|
||||
- **Daily**
|
||||
- **Weekly**
|
||||
|
||||
### Vulnerability Management
|
||||
|
||||
Review and manage vulnerabilities:
|
||||
|
||||
```bash
|
||||
# Security scan results
|
||||
Critical: 2 vulnerabilities
|
||||
High: 5 vulnerabilities
|
||||
Medium: 12 vulnerabilities
|
||||
Low: 8 vulnerabilities
|
||||
```
|
||||
|
||||
### Network Policies
|
||||
|
||||
Restrict network access:
|
||||
|
||||
```yaml
|
||||
# Network policy example
|
||||
network_policy:
|
||||
egress:
|
||||
- allow:
|
||||
- dns: true
|
||||
- http: ["api.example.com"]
|
||||
- https: ["github.com", "registry.npmjs.org"]
|
||||
ingress:
|
||||
- allow:
|
||||
- port: 8080
|
||||
from: ["load-balancer"]
|
||||
```
|
||||
|
||||
### Secrets Management
|
||||
|
||||
Best practices for secrets:
|
||||
|
||||
1. **Never commit secrets** to version control
|
||||
2. **Use Containr secrets** for sensitive data
|
||||
3. **Rotate secrets regularly**
|
||||
4. **Use least privilege** principle
|
||||
|
||||
```bash
|
||||
# Good: Use environment variables
|
||||
DATABASE_URL=${DATABASE_URL}
|
||||
|
||||
# Bad: Hardcoded secrets
|
||||
DATABASE_URL=postgresql://user:password@host:5432/db
|
||||
```
|
||||
|
||||
## Scaling Policies
|
||||
|
||||
### Manual Scaling
|
||||
|
||||
Set replica count manually:
|
||||
|
||||
```yaml
|
||||
# Manual scaling configuration
|
||||
scaling:
|
||||
replicas: 3 # Run 3 instances
|
||||
```
|
||||
|
||||
### Auto-Scaling
|
||||
|
||||
Configure automatic scaling:
|
||||
|
||||
```yaml
|
||||
# Auto-scaling configuration
|
||||
scaling:
|
||||
min_replicas: 1
|
||||
max_replicas: 10
|
||||
metrics:
|
||||
- type: "cpu"
|
||||
target: "70%" # Scale when CPU > 70%
|
||||
- type: "memory"
|
||||
target: "80%" # Scale when memory > 80%
|
||||
- type: "requests_per_second"
|
||||
target: 100 # Scale when RPS > 100
|
||||
policies:
|
||||
scale_up_cooldown: "60s" # Wait 60s between scale-ups
|
||||
scale_down_cooldown: "300s" # Wait 5m between scale-downs
|
||||
```
|
||||
|
||||
### Scaling Strategies
|
||||
|
||||
Different scaling strategies for different needs:
|
||||
|
||||
#### CPU-Based Scaling
|
||||
```yaml
|
||||
scaling:
|
||||
metrics:
|
||||
- type: "cpu"
|
||||
target: "70%"
|
||||
```
|
||||
|
||||
#### Memory-Based Scaling
|
||||
```yaml
|
||||
scaling:
|
||||
metrics:
|
||||
- type: "memory"
|
||||
target: "80%"
|
||||
```
|
||||
|
||||
#### Request-Based Scaling
|
||||
```yaml
|
||||
scaling:
|
||||
metrics:
|
||||
- type: "requests_per_second"
|
||||
target: 100
|
||||
```
|
||||
|
||||
#### Custom Metrics
|
||||
```yaml
|
||||
scaling:
|
||||
metrics:
|
||||
- type: "custom"
|
||||
name: "queue_length"
|
||||
target: 50
|
||||
```
|
||||
|
||||
## Custom Domains and SSL
|
||||
|
||||
### Domain Configuration
|
||||
|
||||
Set up custom domains with advanced options:
|
||||
|
||||
```yaml
|
||||
# Domain configuration
|
||||
domains:
|
||||
- name: "app.yourdomain.com"
|
||||
type: "primary"
|
||||
ssl: true
|
||||
redirect_www: true
|
||||
- name: "api.yourdomain.com"
|
||||
type: "api"
|
||||
ssl: true
|
||||
- name: "cdn.yourdomain.com"
|
||||
type: "cdn"
|
||||
ssl: true
|
||||
cache_ttl: "1h"
|
||||
```
|
||||
|
||||
### SSL Certificates
|
||||
|
||||
SSL is automatically configured:
|
||||
|
||||
1. **Automatic provisioning**: Let's Encrypt certificates
|
||||
2. **Auto-renewal**: Certificates renewed 30 days before expiry
|
||||
3. **Wildcard support**: For `*.yourdomain.com`
|
||||
4. **Custom certificates**: Upload your own certificates
|
||||
|
||||
### CDN Integration
|
||||
|
||||
Configure CDN for static assets:
|
||||
|
||||
```yaml
|
||||
# CDN configuration
|
||||
cdn:
|
||||
enabled: true
|
||||
provider: "cloudflare" # cloudflare, fastly, custom
|
||||
cache_ttl: "1d"
|
||||
compression: true
|
||||
minify: true
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
### HTTP Health Checks
|
||||
|
||||
Configure HTTP health checks:
|
||||
|
||||
```yaml
|
||||
# HTTP health check
|
||||
health_check:
|
||||
type: "http"
|
||||
path: "/health"
|
||||
method: "GET"
|
||||
expected_status: 200
|
||||
headers:
|
||||
User-Agent: "Containr-Health-Check"
|
||||
timeout: "10s"
|
||||
interval: "30s"
|
||||
retries: 3
|
||||
start_period: "60s"
|
||||
```
|
||||
|
||||
### TCP Health Checks
|
||||
|
||||
For services that don't have HTTP endpoints:
|
||||
|
||||
```yaml
|
||||
# TCP health check
|
||||
health_check:
|
||||
type: "tcp"
|
||||
port: 8080
|
||||
timeout: "5s"
|
||||
interval: "30s"
|
||||
retries: 3
|
||||
```
|
||||
|
||||
### Custom Health Checks
|
||||
|
||||
Implement custom health check logic:
|
||||
|
||||
```javascript
|
||||
// Express.js example
|
||||
app.get('/health', (req, res) => {
|
||||
const health = {
|
||||
status: 'ok',
|
||||
timestamp: new Date().toISOString(),
|
||||
checks: {
|
||||
database: checkDatabase(),
|
||||
redis: checkRedis(),
|
||||
memory: checkMemory()
|
||||
}
|
||||
};
|
||||
|
||||
const isHealthy = Object.values(health.checks).every(check => check.status === 'ok');
|
||||
res.status(isHealthy ? 200 : 503).json(health);
|
||||
});
|
||||
|
||||
function checkDatabase() {
|
||||
// Check database connection
|
||||
return { status: 'ok', latency: '5ms' };
|
||||
}
|
||||
|
||||
function checkRedis() {
|
||||
// Check Redis connection
|
||||
return { status: 'ok', latency: '2ms' };
|
||||
}
|
||||
|
||||
function checkMemory() {
|
||||
const usage = process.memoryUsage();
|
||||
const isHealthy = usage.heapUsed < 512 * 1024 * 1024; // 512MB
|
||||
return {
|
||||
status: isHealthy ? 'ok' : 'error',
|
||||
usage: `${Math.round(usage.heapUsed / 1024 / 1024)}MB`
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Advanced Examples
|
||||
|
||||
### Microservices Architecture
|
||||
|
||||
Example of a microservices setup:
|
||||
|
||||
```yaml
|
||||
# API Gateway
|
||||
services:
|
||||
- name: "api-gateway"
|
||||
type: "web"
|
||||
resources:
|
||||
cpu: "500m"
|
||||
memory: "256Mi"
|
||||
scaling:
|
||||
min_replicas: 2
|
||||
max_replicas: 5
|
||||
domains:
|
||||
- name: "api.yourdomain.com"
|
||||
|
||||
# User Service
|
||||
- name: "user-service"
|
||||
type: "web"
|
||||
resources:
|
||||
cpu: "200m"
|
||||
memory: "128Mi"
|
||||
scaling:
|
||||
min_replicas: 1
|
||||
max_replicas: 3
|
||||
|
||||
# Database
|
||||
- name: "user-db"
|
||||
type: "database"
|
||||
database_type: "postgresql"
|
||||
resources:
|
||||
storage: "20Gi"
|
||||
```
|
||||
|
||||
### Full-Stack Application
|
||||
|
||||
Example with frontend, backend, and database:
|
||||
|
||||
```yaml
|
||||
# Frontend (React/Vue)
|
||||
services:
|
||||
- name: "frontend"
|
||||
type: "web"
|
||||
build:
|
||||
builder: "nixpacks"
|
||||
build_command: "npm run build"
|
||||
start_command: "npm run start"
|
||||
domains:
|
||||
- name: "app.yourdomain.com"
|
||||
|
||||
# Backend (Node.js)
|
||||
- name: "backend"
|
||||
type: "web"
|
||||
build:
|
||||
builder: "nixpacks"
|
||||
start_command: "npm start"
|
||||
environment:
|
||||
DATABASE_URL: "postgresql://user-db:5432/myapp"
|
||||
REDIS_URL: "redis://redis:6379"
|
||||
scaling:
|
||||
min_replicas: 1
|
||||
max_replicas: 5
|
||||
|
||||
# Database
|
||||
- name: "user-db"
|
||||
type: "database"
|
||||
database_type: "postgresql"
|
||||
resources:
|
||||
storage: "10Gi"
|
||||
|
||||
# Cache
|
||||
- name: "redis"
|
||||
type: "database"
|
||||
database_type: "redis"
|
||||
resources:
|
||||
memory: "256Mi"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Build Failures
|
||||
- Check build logs for specific errors
|
||||
- Verify `nixpacks.toml` or `Dockerfile` syntax
|
||||
- Ensure all dependencies are declared
|
||||
|
||||
#### Runtime Errors
|
||||
- Check environment variables
|
||||
- Verify health check endpoints
|
||||
- Review resource limits
|
||||
|
||||
#### Scaling Issues
|
||||
- Monitor metrics during scaling events
|
||||
- Check scaling policies and thresholds
|
||||
- Review resource allocation
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug mode for troubleshooting:
|
||||
|
||||
```yaml
|
||||
# Debug configuration
|
||||
debug:
|
||||
enabled: true
|
||||
log_level: "debug"
|
||||
verbose_logs: true
|
||||
profile_requests: true
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Start small** and scale based on metrics
|
||||
2. **Monitor resource usage** regularly
|
||||
3. **Use health checks** for all services
|
||||
4. **Implement proper logging** and monitoring
|
||||
5. **Secure your applications** with proper secrets management
|
||||
6. **Test scaling policies** in staging environment
|
||||
7. **Regular security scans** and updates
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Learn about [Monitoring and Alerts](./monitoring.md)
|
||||
- Explore [CI/CD Integration](./cicd.md)
|
||||
- Understand [Backup and Recovery](./backup.md)
|
||||
- Review [Performance Optimization](./performance.md)
|
||||
@@ -0,0 +1,260 @@
|
||||
# Getting Started with Containr
|
||||
|
||||
Welcome to Containr! This guide will walk you through setting up your first project and deploying your first application.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, make sure you have:
|
||||
|
||||
- A Containr instance running (either self-hosted or using our hosted version)
|
||||
- A Git repository with your application code
|
||||
- Basic knowledge of Docker and containerization concepts
|
||||
|
||||
## Step 1: Create Your Account
|
||||
|
||||
1. Navigate to your Containr instance URL
|
||||
2. Click "Sign Up" in the top-right corner
|
||||
3. Fill in your email, name, and password
|
||||
4. Verify your email address (if required)
|
||||
5. Log in to your new account
|
||||
|
||||
## Step 2: Create Your First Project
|
||||
|
||||
1. From the dashboard, click "New Project"
|
||||
2. Enter a project name (e.g., "my-awesome-app")
|
||||
3. Add an optional description
|
||||
4. Click "Create Project"
|
||||
|
||||
You'll be taken to your project's main canvas view.
|
||||
|
||||
## Step 3: Connect Your Git Repository
|
||||
|
||||
### Option A: Using GitHub (Recommended)
|
||||
|
||||
1. Click "Add Service" → "Connect Git Repository"
|
||||
2. Select "GitHub" as the provider
|
||||
3. Click "Connect to GitHub" and authorize Containr
|
||||
4. Browse your repositories and select the one you want to deploy
|
||||
5. Choose the branch (usually `main` or `master`)
|
||||
6. Select the root directory if your app isn't in the root
|
||||
7. Click "Connect Repository"
|
||||
|
||||
### Option B: Using Other Git Providers
|
||||
|
||||
Containr also supports GitLab and Bitbucket:
|
||||
|
||||
1. Click "Add Service" → "Connect Git Repository"
|
||||
2. Select your preferred provider
|
||||
3. Follow the authorization flow
|
||||
4. Select your repository and branch
|
||||
|
||||
## Step 4: Configure Your Service
|
||||
|
||||
After connecting your repository, Containr will:
|
||||
|
||||
1. **Auto-detect your stack** (Node.js, Python, Go, etc.)
|
||||
2. **Generate a build plan** using Nixpacks
|
||||
3. **Show you the configuration**
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
- **Service Name**: Give your service a descriptive name
|
||||
- **Build Command**: Auto-detected, but you can customize
|
||||
- **Start Command**: Auto-detected, but you can customize
|
||||
- **Environment Variables**: Add any needed variables
|
||||
|
||||
### Example: Node.js Application
|
||||
|
||||
For a typical Node.js app:
|
||||
|
||||
```bash
|
||||
# Build Command (auto-detected)
|
||||
npm install && npm run build
|
||||
|
||||
# Start Command (auto-detected)
|
||||
npm start
|
||||
```
|
||||
|
||||
### Example: Go Application
|
||||
|
||||
For a Go application:
|
||||
|
||||
```bash
|
||||
# Build Command (auto-detected)
|
||||
go build -o app .
|
||||
|
||||
# Start Command (auto-detected)
|
||||
./app
|
||||
```
|
||||
|
||||
## Step 5: Add Environment Variables
|
||||
|
||||
Most applications need environment variables:
|
||||
|
||||
1. Go to the "Variables" tab in your service
|
||||
2. Add your variables as key-value pairs:
|
||||
- `NODE_ENV=production`
|
||||
- `DATABASE_URL=postgresql://...`
|
||||
- `API_KEY=your-secret-key`
|
||||
3. Variables are automatically encrypted and injected at runtime
|
||||
|
||||
## Step 6: Deploy Your Application
|
||||
|
||||
1. Click "Deploy" in the top-right corner
|
||||
2. Choose your deployment method:
|
||||
- **Deploy Latest Commit**: Deploy the latest commit from your branch
|
||||
- **Manual Deploy**: Specify a commit SHA
|
||||
3. Click "Start Deployment"
|
||||
|
||||
Containr will:
|
||||
1. Pull your code from Git
|
||||
2. Build a Docker image using Nixpacks
|
||||
3. Start the container
|
||||
4. Assign a public URL
|
||||
|
||||
## Step 7: Monitor Your Deployment
|
||||
|
||||
While deploying, you can:
|
||||
|
||||
- **View Build Logs**: See the build process in real-time
|
||||
- **Check Status**: Monitor deployment progress
|
||||
- **Get Notifications**: Receive alerts on success or failure
|
||||
|
||||
Once deployed, you'll see:
|
||||
|
||||
- **Public URL**: Your application is live at `https://your-service-name.containr.app`
|
||||
- **Status**: Green checkmark if running successfully
|
||||
- **Metrics**: CPU, memory, and network usage
|
||||
|
||||
## Step 8: Add a Database (Optional)
|
||||
|
||||
Most applications need a database:
|
||||
|
||||
1. Click "Add Service" → "Add Database"
|
||||
2. Choose your database type:
|
||||
- **PostgreSQL**: For relational data
|
||||
- **Redis**: For caching and sessions
|
||||
- **MySQL**: For MySQL compatibility
|
||||
3. Configure:
|
||||
- Database name
|
||||
- Version
|
||||
- Size allocation
|
||||
4. Click "Create Database"
|
||||
|
||||
### Connect Your Application
|
||||
|
||||
Once the database is created:
|
||||
|
||||
1. Go to your service's "Variables" tab
|
||||
2. Add the database connection URL:
|
||||
```
|
||||
DATABASE_URL=postgresql://username:password@hostname:port/database_name
|
||||
```
|
||||
3. Redeploy your application
|
||||
|
||||
## Step 9: Set Up Preview Environments
|
||||
|
||||
Enable automatic preview environments for pull requests:
|
||||
|
||||
1. Go to project settings
|
||||
2. Enable "Preview Environments"
|
||||
3. Configure:
|
||||
- Automatic cleanup (e.g., 7 days)
|
||||
- Branch patterns (e.g., `feature/*`, `fix/*`)
|
||||
4. Save settings
|
||||
|
||||
Now when you create a pull request:
|
||||
- A preview environment is automatically created
|
||||
- You get a unique URL for testing
|
||||
- Environment is cleaned up after merging
|
||||
|
||||
## Step 10: Configure Custom Domain (Optional)
|
||||
|
||||
To use your own domain:
|
||||
|
||||
1. Go to your service's "Settings" tab
|
||||
2. Click "Add Custom Domain"
|
||||
3. Enter your domain (e.g., `app.yourdomain.com`)
|
||||
4. Configure DNS:
|
||||
```
|
||||
CNAME app.yourdomain.com -> your-service-name.containr.app
|
||||
```
|
||||
5. Wait for SSL certificate provisioning
|
||||
|
||||
## Troubleshooting Common Issues
|
||||
|
||||
### Build Failures
|
||||
|
||||
**Problem**: Build fails during deployment
|
||||
|
||||
**Solutions**:
|
||||
1. Check build logs for specific error messages
|
||||
2. Verify your `package.json`, `go.mod`, or `requirements.txt` is valid
|
||||
3. Ensure all dependencies are properly declared
|
||||
4. Check for syntax errors in your code
|
||||
|
||||
### Runtime Errors
|
||||
|
||||
**Problem**: Application starts but crashes
|
||||
|
||||
**Solutions**:
|
||||
1. Check runtime logs in the "Logs" tab
|
||||
2. Verify environment variables are correctly set
|
||||
3. Ensure your application listens on the correct port (default: `$PORT`)
|
||||
4. Check database connection strings
|
||||
|
||||
### Port Issues
|
||||
|
||||
**Problem**: Application can't be accessed
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure your application listens on the `$PORT` environment variable
|
||||
2. Don't hardcode ports in your application
|
||||
3. Example for Node.js:
|
||||
```javascript
|
||||
const port = process.env.PORT || 3000;
|
||||
app.listen(port, () => {
|
||||
console.log(`Server running on port ${port}`);
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Security
|
||||
|
||||
1. **Never commit secrets** to your repository
|
||||
2. **Use environment variables** for all sensitive data
|
||||
3. **Enable HTTPS** (automatic on Containr)
|
||||
4. **Keep dependencies updated**
|
||||
|
||||
### Performance
|
||||
|
||||
1. **Optimize Docker images** by using `.dockerignore`
|
||||
2. **Enable caching** for faster builds
|
||||
3. **Monitor resource usage** and scale as needed
|
||||
4. **Use CDN** for static assets
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Use feature branches** for new features
|
||||
2. **Enable preview environments** for testing
|
||||
3. **Write tests** and run them in CI/CD
|
||||
4. **Monitor deployments** and set up alerts
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you have your first application deployed:
|
||||
|
||||
- Explore the [Advanced Configuration](./advanced-configuration.md) guide
|
||||
- Learn about [Scaling and Load Balancing](./scaling.md)
|
||||
- Set up [Monitoring and Alerts](./monitoring.md)
|
||||
- Join our [Community](https://github.com/your-org/containr/discussions)
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **Documentation**: [containr.dev/docs](https://containr.dev/docs)
|
||||
- **Community**: [GitHub Discussions](https://github.com/your-org/containr/discussions)
|
||||
- **Support**: support@containr.dev
|
||||
- **Status**: [status.containr.dev](https://status.containr.dev)
|
||||
|
||||
Happy deploying! 🚀
|
||||
Reference in New Issue
Block a user