From b706fca51d68ab5502afd80f8ab649e9aa5e4147 Mon Sep 17 00:00:00 2001 From: raghavyuva Date: Mon, 30 Jun 2025 23:39:52 +0530 Subject: [PATCH 1/4] docs: add go version 1.23.6 installation guide --- docs/contributing/installing_go.md | 149 +++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/contributing/installing_go.md diff --git a/docs/contributing/installing_go.md b/docs/contributing/installing_go.md new file mode 100644 index 00000000..7edbe48a --- /dev/null +++ b/docs/contributing/installing_go.md @@ -0,0 +1,149 @@ +# Installing Go 1.23.6 + +This guide will help you install Go version 1.23.6 on Linux systems. + +## Prerequisites + +- Linux system with curl installed +- sudo privileges +- Terminal access + +## Installation Steps + +### 1. Download Go 1.23.6 + +Download the official Go 1.23.6 tarball for Linux: + +```bash +curl -LO https://go.dev/dl/go1.23.6.linux-amd64.tar.gz +``` + +The `-L` flag follows redirects and `-O` saves the file with the original filename. + +### 2. Remove Previous Go Installation + +Remove any existing Go installation to avoid conflicts: + +```bash +sudo rm -rf /usr/local/go +``` + +### 3. Extract Go to /usr/local + +Extract the downloaded tarball to the standard location: + +```bash +sudo tar -C /usr/local -xzf go1.23.6.linux-amd64.tar.gz +``` + +### 4. Configure Environment Variables + +Add Go to your system PATH by editing your shell profile: + +```bash +nano ~/.bashrc +``` + +Add this line to the end of the file: + +```bash +export PATH=$PATH:/usr/local/go/bin +``` + +Save and exit the editor (Ctrl+O, Enter, Ctrl+X). + +Reload your shell profile: + +```bash +source ~/.bashrc +``` + +### 5. Verify Installation + +Check that Go is properly installed: + +```bash +go version +``` + +You should see output similar to: + +``` +go version go1.23.6 linux/amd64 +``` + +### 6. Clean Up + +Remove the downloaded tarball to free disk space: + +```bash +rm go1.23.6.linux-amd64.tar.gz +``` + +## Alternative Installation Methods + +### Using Package Manager + +For Ubuntu/Debian: + +```bash +sudo apt update +sudo apt install golang-go +``` + +For CentOS/RHEL/Fedora: + +```bash +sudo dnf install golang +``` + +### Using Go Version Manager (gvm) + +Install gvm and then install Go 1.23.6: + +```bash +bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer) +source ~/.gvm/scripts/gvm +gvm install go1.23.6 +gvm use go1.23.6 --default +``` + +## Troubleshooting + +### Go Command Not Found + +If `go version` returns "command not found": + +1. Verify the PATH is set correctly: + ```bash + echo $PATH + ``` + +2. Check if Go is in the expected location: + ```bash + ls -la /usr/local/go/bin/go + ``` + +3. Restart your terminal or run: + ```bash + source ~/.bashrc + ``` + +### Permission Denied + +If you encounter permission errors: + +1. Ensure you have sudo privileges +2. Check file permissions: + ```bash + ls -la /usr/local/go/bin/go + ``` + +## Next Steps + +After installation, you can: + +- Set up your Go workspace: `mkdir ~/go` +- Configure GOPATH and GOPROXY if needed +- Install Go tools: `go install golang.org/x/tools/gopls@latest` +- Start your first Go project: `go mod init myproject` \ No newline at end of file From 8736bfbc7614a4c8929742dcd4565fdfe011c3ca Mon Sep 17 00:00:00 2001 From: raghavyuva Date: Tue, 1 Jul 2025 01:11:34 +0530 Subject: [PATCH 2/4] chore: remove docker and self hosting related guide from documentation --- docs/contributing/docker.md | 589 ------------------------------ docs/contributing/self-hosting.md | 465 ----------------------- 2 files changed, 1054 deletions(-) delete mode 100644 docs/contributing/docker.md delete mode 100644 docs/contributing/self-hosting.md diff --git a/docs/contributing/docker.md b/docs/contributing/docker.md deleted file mode 100644 index aebdeea5..00000000 --- a/docs/contributing/docker.md +++ /dev/null @@ -1,589 +0,0 @@ ---- -title: "Docker Contributions" -sidebar_label: "Docker" ---- - -# Contributing to Nixopus Docker Builds - -This guide provides detailed instructions for contributing to Nixopus Docker builds and container optimization. - -## Overview - -Docker is central to Nixopus deployment strategy. Contributions to Docker builds can include: - -- Optimizing Docker images for size and security -- Improving build performance -- Enhancing multi-stage builds -- Configuring container orchestration -- Supporting new container platforms - -## Understanding the Docker Structure - -Nixopus uses Docker for containerization with the following key components: - -``` -/ -├── api/ -│ └── Dockerfile # API service Dockerfile -├── view/ -│ └── Dockerfile # Frontend Dockerfile -├── docker-compose.yml # Main compose file -└── docker-compose-staging.yml # Staging environment compose file -``` - -## Best Practices for Docker Contributions - -### 1. Image Optimization - -When optimizing Docker images: - -1. **Use Multi-Stage Builds** - - Example improvement for the API Dockerfile: - - ```dockerfile - # Build stage - FROM golang:1.21-alpine AS builder - - WORKDIR /app - COPY go.mod go.sum ./ - RUN go mod download - - COPY . . - RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . - - # Final stage - FROM alpine:3.18 - - RUN apk --no-cache add ca-certificates tzdata - - WORKDIR /app - COPY --from=builder /app/app . - COPY --from=builder /app/migrations ./migrations - - # Add non-root user - RUN adduser -D -g '' appuser - USER appuser - - CMD ["./app"] - ``` - -2. **Minimize Layer Size** - - Best practices: - - Combine RUN commands with `&&` - - Clean up in the same layer - - Use `.dockerignore` to exclude unnecessary files - - Example: - - ```dockerfile - RUN apk --no-cache add \ - curl \ - tzdata \ - ca-certificates \ - openssl \ - && rm -rf /var/cache/apk/* - ``` - - Example `.dockerignore`: - - ``` - .git - .github - .vscode - node_modules - npm-debug.log - Dockerfile* - docker-compose* - *.md - test/ - **/__tests__ - coverage/ - ``` - -3. **Use Specific Versions** - - Bad: - - ```dockerfile - FROM node:latest - ``` - - Good: - - ```dockerfile - FROM node:20.6.1-alpine3.18 - ``` - -4. **Leverage BuildKit Features** - - ```dockerfile - # syntax=docker/dockerfile:1.4 - - # Enable BuildKit cache mounts for faster builds - RUN --mount=type=cache,target=/var/cache/apt \ - --mount=type=cache,target=/var/lib/apt \ - apt-get update && apt-get install -y --no-install-recommends \ - curl \ - ca-certificates - ``` - -### 2. Security Improvements - -1. **Use Non-Root Users** - - ```dockerfile - # Create a non-root user - RUN addgroup -S appgroup && adduser -S appuser -G appgroup - - # Set permissions - COPY --chown=appuser:appgroup . . - - # Switch to non-root user - USER appuser - ``` - -2. **Scan Images for Vulnerabilities** - - Implement scanning in your local workflow and document it: - - ```bash - # Using Docker Scout - docker scout cves nixopus-api:latest - - # Using Trivy - trivy image nixopus-api:latest - ``` - -3. **Minimal Base Images** - - Replace general images with minimal alternatives: - - - Use `alpine` instead of full `debian` - - Use `distroless` images for production - - Example: - - ```dockerfile - # Final production stage - FROM gcr.io/distroless/static-debian11 - - COPY --from=builder /app/app / - - CMD ["/app"] - ``` - -### 3. Docker Compose Improvements - -1. **Environment Management** - - ```yaml - services: - api: - env_file: - - .env.common - - .env.${NIXOPUS_ENV:-production} - ``` - -2. **Healthcheck Enhancements** - - ```yaml - services: - api: - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8443/health"] - interval: 10s - timeout: 5s - retries: 3 - start_period: 30s - ``` - -3. **Resource Constraints** - - ```yaml - services: - api: - deploy: - resources: - limits: - cpus: '0.5' - memory: 512M - reservations: - cpus: '0.1' - memory: 128M - ``` - -4. **Dependency Management** - - ```yaml - services: - api: - depends_on: - db: - condition: service_healthy - redis: - condition: service_healthy - ``` - -### 4. CI/CD Integration - -1. **Automated Builds** - - Example GitHub Actions workflow for Docker builds: - - ```yaml - name: Docker Image CI - - on: - push: - branches: [ main ] - tags: [ 'v*' ] - pull_request: - branches: [ main ] - - jobs: - build: - runs-on: ubuntu-latest - strategy: - matrix: - service: [api, view] - steps: - - uses: actions/checkout@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v2 - - - name: Login to GitHub Container Registry - if: github.event_name != 'pull_request' - uses: docker/login-action@v2 - with: - registry: ghcr.io - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - - name: Extract metadata - id: meta - uses: docker/metadata-action@v4 - with: - images: ghcr.io/${{ github.repository }}-${{ matrix.service }} - tags: | - type=semver,pattern={{version}} - type=semver,pattern={{major}}.{{minor}} - type=semver,pattern={{major}} - type=ref,event=branch - type=sha - - - name: Build and push - uses: docker/build-push-action@v4 - with: - context: ./${{ matrix.service }} - push: ${{ github.event_name != 'pull_request' }} - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - cache-from: type=gha,scope=${{ matrix.service }} - cache-to: type=gha,mode=max,scope=${{ matrix.service }} - ``` - -2. **Image Testing** - - Add automated testing for Docker images: - - ```yaml - - name: Test image - run: | - docker run --rm ${{ steps.meta.outputs.tags }} health-check - ``` - -### 5. Container Orchestration - -1. **Kubernetes Support** - - Create Kubernetes manifests for Nixopus: - - ```yaml - # kubernetes/api-deployment.yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: nixopus-api - spec: - replicas: 3 - selector: - matchLabels: - app: nixopus-api - template: - metadata: - labels: - app: nixopus-api - spec: - containers: - - name: api - image: ghcr.io/raghavyuva/nixopus-api:latest - ports: - - containerPort: 8443 - env: - - name: DB_HOST - valueFrom: - configMapKeyRef: - name: nixopus-config - key: db-host - resources: - limits: - cpu: "500m" - memory: "512Mi" - requests: - cpu: "100m" - memory: "128Mi" - livenessProbe: - httpGet: - path: /health - port: 8443 - initialDelaySeconds: 30 - periodSeconds: 10 - readinessProbe: - httpGet: - path: /health - port: 8443 - initialDelaySeconds: 5 - periodSeconds: 5 - ``` - -2. **Docker Swarm Support** - - Create Docker Swarm deployment examples: - - ```yaml - version: '3.8' - - services: - api: - image: ghcr.io/raghavyuva/nixopus-api:latest - deploy: - replicas: 2 - update_config: - parallelism: 1 - delay: 10s - order: start-first - restart_policy: - condition: on-failure - max_attempts: 3 - window: 120s - resources: - limits: - cpus: '0.5' - memory: 512M - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8443/health"] - interval: 10s - timeout: 5s - retries: 3 - start_period: 30s - networks: - - nixopus-network - - networks: - nixopus-network: - driver: overlay - attachable: true - ``` - -## Advanced Docker Features - -### 1. BuildKit Features - -1. **Mount Secrets in Build** - - ```dockerfile - # syntax=docker/dockerfile:1.4 - - FROM alpine - - RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \ - npm ci --production - ``` - - Usage: - - ```bash - docker build --secret id=npmrc,src=.npmrc -t nixopus-view . - ``` - -2. **Leverage Build Cache** - - ```dockerfile - # Cache node modules - COPY package.json yarn.lock ./ - RUN --mount=type=cache,target=/root/.yarn \ - yarn install --frozen-lockfile - ``` - -### 2. Image Variants - -Create specialized image variants: - -1. **Development Image** - - ```dockerfile - FROM nixopus-api:latest AS production - - FROM nixopus-api-base:latest AS development - RUN apk add --no-cache curl jq vim - COPY --from=production /app /app - - # Add development tools and configurations - COPY tools/dev.sh /usr/local/bin/dev-tools - RUN chmod +x /usr/local/bin/dev-tools - - CMD ["sh", "-c", "dev-tools && ./app"] - ``` - -2. **Testing Image** - - ```dockerfile - FROM nixopus-api-base:latest AS testing - - COPY . . - RUN go test -v ./... - - # If tests pass, build the app - RUN go build -o app . - - # Minimal test runner image - FROM alpine:3.18 - COPY --from=testing /app/app /app - CMD ["/app", "--run-tests"] - ``` - -## Monitoring and Observability - -1. **Add Prometheus Metrics** - - ```dockerfile - # Install Prometheus client - RUN go get github.com/prometheus/client_golang/prometheus - - # Expose metrics endpoint - EXPOSE 8080 - - # Add health/readiness checks - HEALTHCHECK --interval=30s --timeout=10s --retries=3 \ - CMD curl -f http://localhost:8080/health || exit 1 - ``` - -2. **Log Management** - - ```dockerfile - # Configure structured logging - ENV LOG_FORMAT=json - ENV LOG_LEVEL=info - - # Forward logs to stdout/stderr for container orchestration - RUN ln -sf /dev/stdout /app/logs/app.log && \ - ln -sf /dev/stderr /app/logs/error.log - ``` - -## Testing Docker Changes - -1. **Local Testing Workflow** - - ```bash - # Build images - docker-compose build - - # Run tests - docker-compose run --rm api go test ./... - - # Start services - docker-compose up -d - - # Check logs - docker-compose logs -f - - # Verify health - curl http://localhost:8443/health - ``` - -2. **Performance Testing** - - ```bash - # Check image size - docker images nixopus-api - - # Check startup time - time docker-compose up -d api - - # Check resource usage - docker stats nixopus-api-container - ``` - -3. **Security Scanning** - - ```bash - # Scan for vulnerabilities - docker scout cves nixopus-api:latest - - # Check for exposed secrets - grype nixopus-api:latest - ``` - -## Submitting Docker Improvements - -1. **Document Changes** - - Include before/after metrics: - - Image size reduction - - Build time improvements - - Security posture enhancements - - Resource utilization changes - -2. **Update Documentation** - - - Update README.md with new Docker features - - Add examples of new Docker configurations - - Document any breaking changes - -3. **Create Pull Request** - - ```bash - git add . - git commit -m "feat(docker): optimize API container size and security" - git push origin feature/docker-improvements - ``` - -4. **PR Details** - - Include in your PR: - - Purpose of changes - - Performance metrics - - Testing methodology - - Screenshots of before/after - -## Common Docker Pitfalls - -1. **Image Bloat Issues** - - Including development dependencies - - Not cleaning up package manager caches - - Copying unnecessary files - -2. **Security Problems** - - Running as root - - Exposing unnecessary ports - - Using outdated base images - - Embedding secrets in the image - -3. **Performance Issues** - - Inefficient layer caching - - Sub-optimal build order - - Missing health checks - - Improper resource constraints - -## Need Help? - -If you need assistance with Docker contributions: - -- Join the #docker channel on Discord -- Review the Docker documentation -- Check existing Docker issues for similar improvements - -Thank you for improving Nixopus Docker builds! diff --git a/docs/contributing/self-hosting.md b/docs/contributing/self-hosting.md deleted file mode 100644 index 4ec7984b..00000000 --- a/docs/contributing/self-hosting.md +++ /dev/null @@ -1,465 +0,0 @@ -# Contributing to Nixopus Self-Hosting - -This guide provides detailed instructions for contributing to the self-hosting capabilities of Nixopus. - -## Overview - -Self-hosting contributions can involve: - -- Improving the installation process -- Enhancing Docker configurations -- Adding support for new deployment environments -- Optimizing performance for self-hosted instances -- Improving backup and restoration processes -- Enhancing security for self-hosted deployments - -## Understanding the Self-Host Architecture - -Nixopus self-hosting uses a containerized architecture with the following components: - -``` -nixopus-api # Backend API service -nixopus-db # PostgreSQL database -nixopus-redis # Redis for caching and pub/sub -nixopus-view # Frontend Next.js application -nixopus-caddy # Caddy web server for reverse proxy -``` - -## Setting Up for Self-Host Development - -1. **Prerequisites** - - Docker and Docker Compose - - Python 3.8 or higher - - Access to a Linux-based system (preferred) - - Basic understanding of containerization - -2. **Environment Setup** - - ```bash - # Clone the repository - git clone https://github.com/raghavyuva/nixopus.git - cd nixopus - - # Create a development branch - git checkout -b feature/self-host-improvement - ``` - -## Key Files for Self-Hosting - -``` -/ -├── docker-compose.yml # Main Docker Compose configuration -├── docker-compose-staging.yml # Staging environment configuration -├── installer/ # Installation scripts -│ ├── install.py # Main installation script -│ ├── environment.py # Environment setup -│ ├── service_manager.py # Service management -│ ├── docker_setup.py # Docker configuration -│ └── validation.py # Validation utilities -├── scripts/ -│ └── install.sh # Installation shell script -└── Makefile # Make targets for common operations -``` - -## Making Self-Hosting Improvements - -### 1. Improving the Installation Process - -When enhancing the installation process: - -1. **Identify Pain Points** - - Look for error-prone steps - - Find areas where users struggle - - Consider platform-specific issues - -2. **Modify Installation Scripts** - - Example improvement to `install.py`: - - ```python - # Add better error handling for network issues - def check_connectivity(self): - try: - response = requests.get("https://registry.hub.docker.com/v2/", timeout=5) - return response.status_code == 200 - except requests.RequestException: - print("\033[31mError: Cannot connect to Docker Hub. Please check your internet connection.\033[0m") - return False - - # Use in installer - if not installer.check_connectivity(): - print("Aborting installation due to connectivity issues.") - sys.exit(1) - ``` - -3. **Update Documentation** - - Reflect your changes in the self-hosting documentation - - Add troubleshooting tips for common issues - -### 2. Enhancing Docker Configurations - -1. **Optimize Container Settings** - - Example improvements: - - ```yaml - # Add health checks to more services - service-name: - image: service-image - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:8080/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - - # Add resource constraints - service-name: - image: service-image - deploy: - resources: - limits: - cpus: '0.50' - memory: 512M - reservations: - cpus: '0.25' - memory: 256M - ``` - -2. **Improve Networking Security** - - ```yaml - # Restrict exposed ports - services: - api: - ports: - # Only expose to localhost - - "127.0.0.1:8443:8443" - - # Use custom networks with isolation - networks: - frontend-network: - name: nixopus-frontend - backend-network: - name: nixopus-backend - internal: true # Not exposed to host network - ``` - -3. **Enhance Volume Management** - - ```yaml - # Use named volumes with better organization - volumes: - postgres-data: - name: nixopus-postgres-data - redis-data: - name: nixopus-redis-data - - services: - db: - volumes: - - postgres-data:/var/lib/postgresql/data - ``` - -### 3. Supporting New Deployment Environments - -1. **Add Environment-Specific Configurations** - - Create new templates for specific environments: - - ```python - def generate_env_config(self, environment): - """Generate environment-specific configuration.""" - if environment == "kubernetes": - return self._generate_kubernetes_config() - elif environment == "aws": - return self._generate_aws_config() - else: - return self._generate_standard_config() - ``` - -2. **Create Environment Detection Logic** - - ```python - def detect_environment(self): - """Detect the current environment.""" - if os.path.exists("/var/run/kubernetes"): - return "kubernetes" - elif os.environ.get("AWS_EXECUTION_ENV"): - return "aws" - elif os.environ.get("AZURE_EXTENSION_DIR"): - return "azure" - else: - return "standard" - ``` - -3. **Add Platform-Specific Instructions** - - For each new platform, create detailed instructions in the documentation. - -### 4. Performance Optimization - -1. **Database Tuning** - - Create a utility script for database optimization: - - ```python - def optimize_postgres_for_hardware(self): - """Optimize PostgreSQL configuration based on available hardware.""" - total_memory = self._get_system_memory_mb() - - # Calculate optimal settings - shared_buffers = max(int(total_memory * 0.25), 128) - effective_cache_size = max(int(total_memory * 0.75), 256) - - # Generate configuration - config = [ - f"shared_buffers = {shared_buffers}MB", - f"effective_cache_size = {effective_cache_size}MB", - "work_mem = 4MB", - "maintenance_work_mem = 64MB", - "max_connections = 100" - ] - - return "\n".join(config) - ``` - -2. **Caching Strategy Improvements** - - Enhance the Redis configuration: - - ```yaml - nixopus-redis: - image: redis:7-alpine - command: > - redis-server - --appendonly yes - --maxmemory 256mb - --maxmemory-policy allkeys-lru - --save 900 1 - --save 300 10 - --save 60 10000 - ``` - -### 5. Backup and Restore Improvements - -1. **Automated Backup System** - - Create a backup service in Docker Compose: - - ```yaml - nixopus-backup: - image: postgres:14-alpine - volumes: - - ${DB_VOLUME:-/etc/nixopus/db}:/source - - ${BACKUP_VOLUME:-/etc/nixopus/backups}:/backups - environment: - - POSTGRES_USER=${USERNAME} - - POSTGRES_PASSWORD=${PASSWORD} - - POSTGRES_DB=${DB_NAME} - command: > - sh -c 'while true; do - pg_dump -U ${USERNAME} -d ${DB_NAME} -h nixopus-db -F c -f /backups/nixopus_$$(date +%Y%m%d_%H%M%S).dump; - find /backups -name "nixopus_*.dump" -type f -mtime +7 -delete; - sleep 86400; - done' - networks: - - nixopus-network - ``` - -2. **Restoration Script Enhancement** - - ```python - def restore_from_backup(self, backup_path): - """Restore database from a backup file.""" - if not os.path.exists(backup_path): - print(f"Error: Backup file {backup_path} not found.") - return False - - try: - print(f"Stopping services...") - self._stop_services() - - print(f"Restoring database from {backup_path}...") - container_name = "nixopus-db-container" - command = [ - "docker", "exec", "-i", container_name, - "pg_restore", "-U", "nixopus", "-d", "nixopus", - "--clean", "--if-exists", "--no-owner", "--no-privileges" - ] - - with open(backup_path, 'rb') as f: - subprocess.run(command, stdin=f, check=True) - - print(f"Restarting services...") - self._start_services() - - return True - except Exception as e: - print(f"Error during restoration: {str(e)}") - return False - ``` - -### 6. Security Enhancements - -1. **Secrets Management** - - Implement a secure secrets management solution: - - ```python - from cryptography.fernet import Fernet - - class SecretsManager: - def __init__(self, key_path): - self.key_path = key_path - self._ensure_key() - - def _ensure_key(self): - """Ensure encryption key exists.""" - if not os.path.exists(self.key_path): - key = Fernet.generate_key() - os.makedirs(os.path.dirname(self.key_path), exist_ok=True) - with open(self.key_path, 'wb') as f: - f.write(key) - os.chmod(self.key_path, 0o600) - - def encrypt(self, value): - """Encrypt a value.""" - with open(self.key_path, 'rb') as f: - key = f.read() - cipher = Fernet(key) - return cipher.encrypt(value.encode()).decode() - - def decrypt(self, value): - """Decrypt a value.""" - with open(self.key_path, 'rb') as f: - key = f.read() - cipher = Fernet(key) - return cipher.decrypt(value.encode()).decode() - ``` - -2. **TLS Configuration for Services** - - Enhance the Caddy configuration for better security: - - ```json - { - "admin": { - "listen": "127.0.0.1:2019" # Only listen on localhost - }, - "logging": { - "logs": { - "default": { - "level": "ERROR" - } - } - }, - "storage": { - "module": "file_system", - "root": "/data" - }, - "apps": { - "tls": { - "certificates": { - "automate": ["your-domain.com"] - }, - "automation": { - "policies": [{ - "issuer": { - "module": "acme", - "challenges": { - "http": { - "disabled": false - }, - "tlsalpn": { - "disabled": true - } - } - } - }] - } - }, - "http": { - "servers": { - "main": { - "listen": [":443"], - "routes": [ - { - "match": [{ - "host": ["your-domain.com"] - }], - "handle": [{ - "handler": "reverse_proxy", - "upstreams": [{ - "dial": "nixopus-api:8443" - }] - }] - } - ] - } - } - } - } - } - ``` - -## Testing Self-Hosting Changes - -1. **Test Installation on Multiple Platforms** - - Ubuntu/Debian - - CentOS/RHEL - - Docker Desktop (Windows/macOS) - -2. **Verify Upgrade Path** - - Test upgrading from previous version - - Ensure configuration is preserved - - Validate data persistence - -3. **Resource Utilization Testing** - - Monitor memory usage - - Track CPU utilization - - Measure disk I/O - - Test with different resource constraints - -4. **Security Testing** - - Verify encryption settings - - Test access controls - - Check for exposed ports/services - - Validate TLS configuration - -## Submitting Self-Hosting Contributions - -1. **Document Your Changes** - - Explain the purpose of your changes - - Provide example configurations - - Include testing results - -2. **Create Pull Request** - - ```bash - git add . - git commit -m "feat(self-host): improve database backup automation" - git push origin feature/self-host-improvement - ``` - -3. **Complete PR Template** - - Include problem description - - Explain your solution - - List tested environments - - Note any limitations - -4. **Run Integration Tests** - - Ensure all services start correctly - - Verify functionality with your changes - - Test error scenarios - - Validate performance implications - -## Need Help? - -If you need assistance with self-hosting contributions: - -- Join the #self-hosting channel on Discord -- Create an issue for specific problems -- Ask in the community forums - -Thank you for improving Nixopus self-hosting! From 2894c703769df9aae0862344a74e43c737a395cd Mon Sep 17 00:00:00 2001 From: raghavyuva Date: Tue, 1 Jul 2025 03:40:22 +0530 Subject: [PATCH 3/4] wip: docs changes for contribution guidelines --- api/api/versions.json | 2 +- docs/.vitepress/components/CodeGroup.vue | 203 +++++++++++++++ docs/.vitepress/config.mts | 58 ++++- docs/.vitepress/theme/index.ts | 2 + docs/contributing/backend.md | 179 ------------- .../backend/backend-architecture.md | 184 +++++++++++++ .../backend/migrations-and-fixtures.md | 0 docs/contributing/backend/overview.md | 122 +++++++++ docs/contributing/backend/testing.md | 0 .../documentation-architecture.md | 0 .../documentation/documentation.md | 0 .../frontend/frontend-architecture.md | 0 docs/contributing/frontend/overview.md | 0 .../getting-involved/making-changes.md | 0 .../getting-involved/proposing-changes.md | 0 docs/contributing/index.md | 243 ++++++++++-------- 16 files changed, 699 insertions(+), 294 deletions(-) create mode 100644 docs/.vitepress/components/CodeGroup.vue create mode 100644 docs/contributing/backend/backend-architecture.md create mode 100644 docs/contributing/backend/migrations-and-fixtures.md create mode 100644 docs/contributing/backend/overview.md create mode 100644 docs/contributing/backend/testing.md create mode 100644 docs/contributing/documentation/documentation-architecture.md create mode 100644 docs/contributing/documentation/documentation.md create mode 100644 docs/contributing/frontend/frontend-architecture.md create mode 100644 docs/contributing/frontend/overview.md create mode 100644 docs/contributing/getting-involved/making-changes.md create mode 100644 docs/contributing/getting-involved/proposing-changes.md diff --git a/api/api/versions.json b/api/api/versions.json index 28f73096..f38fd31e 100644 --- a/api/api/versions.json +++ b/api/api/versions.json @@ -3,7 +3,7 @@ { "version": "v1", "status": "active", - "release_date": "2025-06-30T20:48:43.246107+05:30", + "release_date": "2025-07-01T03:25:00.821854+05:30", "end_of_life": "0001-01-01T00:00:00Z", "changes": [ "Initial API version" diff --git a/docs/.vitepress/components/CodeGroup.vue b/docs/.vitepress/components/CodeGroup.vue new file mode 100644 index 00000000..62045605 --- /dev/null +++ b/docs/.vitepress/components/CodeGroup.vue @@ -0,0 +1,203 @@ + + + + + \ No newline at end of file diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 05b840c8..511b7a5a 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -52,7 +52,8 @@ export default withMermaid( nav: [ { text: 'Home', link: '/' }, { text: 'Get Started', link: '/install/index.md' }, - { text: 'Blog', link: '/blog/' } + { text: 'Blog', link: '/blog/' }, + { text: 'Ask', link: 'https://discord.com/invite/skdcq39Wpv' } ], footer: { message: `Made with love
Released under the Functional Source License (FSL)`, @@ -88,14 +89,55 @@ export default withMermaid( items: [ { text: 'Contribution', + collapsed: false, + collapsedByDefault: true, items: [ - { text: 'Overview', link: '/contributing/index.md' }, - { text: 'Backend', link: '/contributing/backend.md' }, - { text: 'Frontend', link: '/contributing/frontend.md' }, - { text: 'Documentation', link: '/contributing/documentation.md' }, - { text: 'Docker', link: '/contributing/docker.md' }, - { text: 'Self Hosting', link: '/contributing/self-hosting.md' }, - { text: 'Fixtures', link: '/contributing/fixtures.md' } + { + text: 'Overview', link: '/contributing/index.md', collapsed: true + }, + { + text: 'Backend', link: '/contributing/backend.md', + collapsed: true, + items: [ + { text: 'Overview', link: '/contributing/backend/overview.md' }, + { text: 'Architecture', link: '/contributing/backend/backend-architecture.md' }, + { text: "Migrations & Fixtures", link: '/contributing/backend/migrations-and-fixtures.md' }, + { text: 'Testing', link: '/contributing/backend/testing.md' }, + ] + }, + { + text: 'Frontend', + link: '/contributing/frontend.md', + collapsed: true, + items: [ + { text: 'Overview', link: '/contributing/frontend/frontend.md' }, + { text: 'Architecture', link: '/contributing/frontend/frontend-architecture.md' }, + ] + }, + { + text: 'Documentation', + collapsed: true, + link: '/contributing/documentation.md', + items: [ + { text: 'Overview', link: '/contributing/documentation.md' }, + { text: 'Architecture', link: '/contributing/documentation-architecture.md' }, + ] + }, + { + text: 'Getting Involved', + link: '/contributing/getting-involved/making-changes.md', + collapsed: true, + items: [ + { + text: 'Making Changes', + link: '/contributing/getting-involved/making-changes.md', + }, + { + text: "Proposing Changes", + link: '/contributing/getting-involved/proposing-changes.md', + } + ] + } ] }, { text: "Code of Conduct", link: "/code-of-conduct/index.md" }, diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts index 2acff1d5..3189f72b 100644 --- a/docs/.vitepress/theme/index.ts +++ b/docs/.vitepress/theme/index.ts @@ -7,6 +7,7 @@ import './style.css' import spec from '../../src/openapi.json' assert { type: 'json' } import SponsorsMarquee from '../components/SponsorsMarquee.vue' +import CodeGroup from '../components/CodeGroup.vue' export default { extends: DefaultTheme, @@ -16,6 +17,7 @@ export default { // Register custom components app.component('SponsorsMarquee', SponsorsMarquee) + app.component('CodeGroup', CodeGroup) theme.enhanceApp({ app }) } diff --git a/docs/contributing/backend.md b/docs/contributing/backend.md index c6366cee..3ed42066 100644 --- a/docs/contributing/backend.md +++ b/docs/contributing/backend.md @@ -73,185 +73,6 @@ The project includes a comprehensive fixtures system for development and testing *Note: [air](https://github.com/air-verse/air) as a dev-dependency so you can start the backend with the air command.* -## Project Structure - -The backend follows a clean architecture approach: - -``` -api/ -├── internal/ -│ ├── features/ # Feature modules -│ ├── middleware/ # HTTP middleware -│ ├── config/ # Application configuration -│ ├── storage/ # Data storage implementation -│ ├── utils/ # Utility functions -│ └── types/ # Type definitions -├── migrations/ # Database migrations -└── tests/ # Test utilities -``` - -## Adding a New Feature - -1. **Create a New Branch** - - ```bash - git checkout -b feature/your-feature-name - ``` - -2. **Implement Your Feature** - - Create a new directory under `api/internal/features/` with the following structure: - - ``` - api/internal/features/your-feature/ - ├── controller/init.go # HTTP handlers - ├── service/service_name.go # Business logic - ├── storage/dao_name.go # Data access - └── types/type_name.go # Type definitions - ``` - - Here's a sample implementation: - - ```go - // types.go - package yourfeature - - type YourEntity struct { - ID string `json:"id" db:"id"` - Name string `json:"name" db:"name"` - CreatedAt string `json:"created_at" db:"created_at"` - UpdatedAt string `json:"updated_at" db:"updated_at"` - } - - // init.go (Controller) - package yourfeature - - import "github.com/go-fuego/fuego" - - type Controller struct { - service *Service - } - - func NewController(s *Service)*Controller { - return &Controller{service: s} - } - - func (c *Controller) GetEntities(ctx fuego.Context) error { - entities, err := c.service.ListEntities() - if err != nil { - return ctx.JSON(500, map[string]string{"error": err.Error()}) - } - return ctx.JSON(200, entities) - } - - func (c *Controller) CreateEntity(ctx fuego.Context) error { - var input YourEntity - if err := ctx.Bind(&input); err != nil { - return ctx.JSON(400, map[string]string{"error": "invalid input"}) - } - created, err := c.service.CreateEntity(&input) - if err != nil { - return ctx.JSON(500, map[string]string{"error": err.Error()}) - } - return ctx.JSON(201, created) - } - - // service.go or service_name.go - package yourfeature - - type Service struct { - storage *Storage - } - - func NewService(storage *Storage)*Service { - return &Service{storage: storage} - } - - // init.go or storage.go - package yourfeature - - import ( - "context" - "github.com/uptrace/bun" - ) - - type Storage struct { - DB *bun.DB - Ctx context.Context - } - - func NewFeatureStorage(db *bun.DB, ctx context.Context)*NewFeatureStorage { - return &FeatureStorage{ - DB: db, - Ctx: ctx - } - } - - ``` - -3. **Register Routes** - - Update `api/internal/routes.go` to include your new endpoints: - - ```go - // Register your feature routes - yourFeatureStorage := yourfeature.NewStorage(db) - yourFeatureService := yourfeature.NewService(yourFeatureStorage) - yourFeatureController := yourfeature.NewController(yourFeatureService) - - api := router.Group("/api") - { - // Your feature endpoints - featureGroup := api.Group("/your-feature") - { - featureGroup.GET("/", middleware.Authorize(), yourFeatureController.GetEntities) - featureGroup.POST("/", middleware.Authorize(), yourFeatureController.CreateEntity) - // Add more routes as needed - } - } - ``` - -4. **Add Database Migrations** - - Create migration files in `api/migrations/your-feature/`: - - ```sql - -- seq_number_create_your_feature_table.up.sql - CREATE TABLE your_feature ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - name TEXT NOT NULL, - created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP - ); - - -- seq_number_create_your_feature_table.down.sql - DROP TABLE IF EXISTS your_feature; - ``` - -5. **Write Tests** - - Organize your tests in the `tests/` using a separate folder named after each feature: - - ```go - // controller_test.go - package yourfeature - - import ( - "testing" - // Import other necessary packages - ) - - func TestGetEntity(t *testing.T) { - // Test implementation - } - - // service_test.go - // storage_test.go - ``` - -6. **Update API Documentation** - - Note that the docs will be updated automatically; the OpenAPI specification in `api/doc/openapi.json` will be updated automatically. ## Testing diff --git a/docs/contributing/backend/backend-architecture.md b/docs/contributing/backend/backend-architecture.md new file mode 100644 index 00000000..f2b16a05 --- /dev/null +++ b/docs/contributing/backend/backend-architecture.md @@ -0,0 +1,184 @@ +# Backend architecture + +## Project Structure + +The backend follows a clean architecture approach: + +```sh +. +├── Dockerfile # Dockerfile for building the Docker image +├── Makefile # commands for building and running the project +├── api # API generated client/server stubs from client +├── cmd/fixtures # Entry point for loading fixtures +├── doc +│ └── openapi.json # API schema definition / OpenAPI spec +├── env.test # Environment variables for testing +├── fixtures # Sample yaml data files for test runs +├── go.mod # Dependency management for project +├── internal # Application code / service and core logic +├── main.go # Application entry point +└── migrations # SQL scripts for migrations +``` + +## Adding a New Feature + +1. **Create a New Branch** + + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Implement Your Feature** + + Create a new directory under `api/internal/features/` with the following structure: + + ``` + api/internal/features/your-feature/ + ├── controller/init.go # HTTP handlers + ├── service/service_name.go # Business logic + ├── storage/dao_name.go # Data access + └── types/type_name.go # Type definitions + ``` + + Here's a sample implementation: + + ```go + // types.go + package yourfeature + + type YourEntity struct { + ID string `json:"id" db:"id"` + Name string `json:"name" db:"name"` + CreatedAt string `json:"created_at" db:"created_at"` + UpdatedAt string `json:"updated_at" db:"updated_at"` + } + + // init.go (Controller) + package yourfeature + + import "github.com/go-fuego/fuego" + + type Controller struct { + service *Service + } + + func NewController(s *Service)*Controller { + return &Controller{service: s} + } + + func (c *Controller) GetEntities(ctx fuego.Context) error { + entities, err := c.service.ListEntities() + if err != nil { + return ctx.JSON(500, map[string]string{"error": err.Error()}) + } + return ctx.JSON(200, entities) + } + + func (c *Controller) CreateEntity(ctx fuego.Context) error { + var input YourEntity + if err := ctx.Bind(&input); err != nil { + return ctx.JSON(400, map[string]string{"error": "invalid input"}) + } + created, err := c.service.CreateEntity(&input) + if err != nil { + return ctx.JSON(500, map[string]string{"error": err.Error()}) + } + return ctx.JSON(201, created) + } + + // service.go or service_name.go + package yourfeature + + type Service struct { + storage *Storage + } + + func NewService(storage *Storage)*Service { + return &Service{storage: storage} + } + + // init.go or storage.go + package yourfeature + + import ( + "context" + "github.com/uptrace/bun" + ) + + type Storage struct { + DB *bun.DB + Ctx context.Context + } + + func NewFeatureStorage(db *bun.DB, ctx context.Context)*NewFeatureStorage { + return &FeatureStorage{ + DB: db, + Ctx: ctx + } + } + + ``` + +3. **Register Routes** + + Update `api/internal/routes.go` to include your new endpoints: + + ```go + // Register your feature routes + yourFeatureStorage := yourfeature.NewStorage(db) + yourFeatureService := yourfeature.NewService(yourFeatureStorage) + yourFeatureController := yourfeature.NewController(yourFeatureService) + + api := router.Group("/api") + { + // Your feature endpoints + featureGroup := api.Group("/your-feature") + { + featureGroup.GET("/", middleware.Authorize(), yourFeatureController.GetEntities) + featureGroup.POST("/", middleware.Authorize(), yourFeatureController.CreateEntity) + // Add more routes as needed + } + } + ``` + +4. **Add Database Migrations** + + Create migration files in `api/migrations/your-feature/`: + + ```sql + -- seq_number_create_your_feature_table.up.sql + CREATE TABLE your_feature ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name TEXT NOT NULL, + created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP + ); + + -- seq_number_create_your_feature_table.down.sql + DROP TABLE IF EXISTS your_feature; + ``` + +5. **Write Tests** + + Organize your tests in the `tests/` using a separate folder named after each feature: + + ```go + // controller_test.go + package yourfeature + + import ( + "testing" + // Import other necessary packages + ) + + func TestGetEntity(t *testing.T) { + // Test implementation + } + + // service_test.go + // storage_test.go + ``` + +6. **Update API Documentation** + + Note that the docs will be updated automatically; the OpenAPI specification in `api/doc/openapi.json` will be updated automatically. diff --git a/docs/contributing/backend/migrations-and-fixtures.md b/docs/contributing/backend/migrations-and-fixtures.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/backend/overview.md b/docs/contributing/backend/overview.md new file mode 100644 index 00000000..c0aeaa6b --- /dev/null +++ b/docs/contributing/backend/overview.md @@ -0,0 +1,122 @@ +# Contributing to Backend + +This guide provides detailed instructions for contributing to the Nixopus backend codebase. Whether you're fixing bugs, adding new features, or improving existing functionality, this guide will help you get started quickly. + +Quick Start If you're new to Go development or this codebase, start with the [General Contributing Guide](../index.md) first for the complete setup process. + +## Setup for Backend Development + +Prerequisites Before you begin, ensure you have the following tools installed on your system: + +| Dependency | Version/Details | +|------------|----------------| +| **Go** | 1.23.6 or newer | +| **PostgreSQL** | Any recent version | +| **Docker and Docker Compose** | Recommended for easy setup | +| **Git** | Any recent version | + +2. **Environment Setup** + +Important Make sure you have Docker running before executing these commands. + +```bash +# Clone the repository +git clone https://github.com/raghavyuva/nixopus.git +cd nixopus +``` + +### Copy environment templates +These files contain configuration for database connections, API keys, and other settings +``` +cp api/.env.sample api/.env +``` + +### Set up PostgreSQL database using Docker +This creates a containerized database that's isolated from your system + +``` +docker run -d \ + --name nixopus-db \ + --env-file ./api/.env \ + -p 5432:5432 \ + -v ./data:/var/lib/postgresql/data \ + postgres:14-alpine +``` + +### Install development tools and dependencies +``` +go install github.com/air-verse/air@latest # Hot reload tool for Go development +cd api +go mod download # Download Go dependencies +``` + +3. **Loading Development Fixtures** + +Recommended Fixtures provide sample data to help you develop and test features without starting from scratch. + +The project includes a comprehensive fixtures system for development and testing. You can load sample data using the following commands: + +```bash + +# Load fixtures without affecting existing data +make fixtures-load + +# Drop and recreate all tables, then load fixtures (clean slate) +make fixtures-recreate + +# Truncate all tables, then load fixtures +make fixtures-clean + +# Get help on fixtures commands +make fixtures-help +``` + +**Available Fixture Files:** + +| Fixture File | Description | +|--------------|-------------| +| `complete.yml` | Loads all fixtures (recommended for first-time setup) | +| `users.yml` | Sample user accounts for testing | +| `organizations.yml` | Sample organizations and teams | +| `roles.yml` | User roles and permissions | +| `permissions.yml` | System permissions | +| `role_permissions.yml` | Role-permission mappings | +| `feature_flags.yml` | Feature flag configurations | +| `organization_users.yml` | User-organization relationships | + +Pro Tip The `complete.yml` file uses import statements to load all individual files, making it easy to get a full development environment set up quickly. + +## Running the Backend + +Ready to Start Now that your environment is set up, you can start developing! + +### Start the Development Server + +```bash +air +``` + +This command starts the backend server with hot reloading enabled. The server will automatically restart when you make changes to your code. + +### Verify the Setup + +Once the server is running, you can verify everything is working by visiting: + +- **Health Check**: [`http://localhost:8080/api/v1/health`](http://localhost:8080/api/v1/health) +- **Swagger UI**: [`http://localhost:8080/swagger/index.html`](http://localhost:8080/swagger/index.html) - Interactive API documentation powered by Fuego +- **OpenAPI Spec**: [`http://localhost:8080/swagger/openapi.json`](http://localhost:8080/swagger/openapi.json) - Raw OpenAPI specification file + +Development Tips +- The server runs on port `8080` by default +- Database migrations run automatically on startup +- Hot reloading means you don't need to restart the server for most changes +- Check the terminal output for any error messages + +## Next Steps + +Now that your backend is running, you can: + +- **Explore the Codebase**: Check out the [Project Structure](#project-structure) section below +- **Start the Frontend**: Follow the [Frontend Development Guide](../frontend/frontend.md) +- **Write Your First Feature**: See the [Adding a New Feature](#adding-a-new-feature) section +- **Run Tests**: Learn about [Testing](#testing) your code \ No newline at end of file diff --git a/docs/contributing/backend/testing.md b/docs/contributing/backend/testing.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/documentation/documentation-architecture.md b/docs/contributing/documentation/documentation-architecture.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/documentation/documentation.md b/docs/contributing/documentation/documentation.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/frontend/frontend-architecture.md b/docs/contributing/frontend/frontend-architecture.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/frontend/overview.md b/docs/contributing/frontend/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/getting-involved/making-changes.md b/docs/contributing/getting-involved/making-changes.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/getting-involved/proposing-changes.md b/docs/contributing/getting-involved/proposing-changes.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 927982cc..0ec83c54 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,32 +1,18 @@ -# Contributing to Nixopus +# Contribution Guidelines -Thank you for your interest in contributing to Nixopus! This guide will help you get started with the development setup and explain the contribution process. +Welcome to the Nixopus Contribution Guidelines. This page serves as an index to our detailed contribution guides. We value and appreciate all contributions to the project, whether they're bug fixes, feature additions, documentation improvements, or any other enhancements. -## Table of Contents +## Choose Your Contribution Area -- [Contributing to Nixopus](#contributing-to-nixopus) - - [Table of Contents](#table-of-contents) - - [Specialized Contribution Guides](#specialized-contribution-guides) - - [Code of Conduct](#code-of-conduct) - - [Development Setup](#development-setup) - - [Running the Application](#running-the-application) - - [Making Changes](#making-changes) - - [Submitting a Pull Request](#submitting-a-pull-request) - - [Proposing New Features](#proposing-new-features) - - [Extending Documentation](#extending-documentation) - - [Gratitude](#gratitude) +Each specialized guide provides detailed instructions for contributing to specific aspects of Nixopus: -## Specialized Contribution Guides +| Contribution Guide | Description | Key Topics | +|-------------------|-------------|------------| +| [General Contributing](index.md) | General contribution workflow | Basic setup, making changes, pull request process | +| [Backend Development](backend/backend.md) | Go backend contributions | API features, database migrations, testing | +| [Frontend Development](frontend/frontend.md) | Next.js/React frontend | Component development, Redux integration, UI guidelines | +| [Documentation](documentation/documentation.md) | Documentation improvements | Add contents on features, content guidelines, API docs | -We provide detailed guides for specific types of contributions: - -- [Getting Started with contribution](README.md) - For general contribution guidelines -- [Backend Development Guide](backend.md) - For Go backend contributions -- [Frontend Development Guide](frontend.md) - For Next.js/React frontend contributions -- [Documentation Guide](documentation.md) - For improving or extending documentation -- [Self-Hosting Guide](self-hosting.md) - For improving installation and self-hosting -- [Docker Guide](docker.md) - For Docker builds and container optimization -- [Development Fixtures Guide](fixtures.md) - For working with development data and fixtures ## Code of Conduct @@ -34,138 +20,183 @@ Before contributing, please review and agree to our [Code of Conduct](/code-of-c ## Development Setup -If you prefer to set up your development environment manually: +Before diving into the step by step development setup instructions, you can choose between two setups process: +- Automatic Setup: A single script to install all pre-requisite dependencies, install clone the repository, configure ports, launch PSQL container, generate ssh keys and start both backend and frontend in hot reload mode. This is best for setting up repository for the first time. -1. Clone the repository: +- Manual Setup: In this setup, you will have to individually install Docker, Go, Node.js/Yarn, and Git, and clone the repository, copy and customized your .env files to spin up the database in Docker, giving granular control of your env. -```bash -git clone https://github.com/raghavyuva/nixopus.git -cd nixopus -``` +::: details Automatic Setup -2. Install Go (version 1.23.6 or newer), and PostgreSQL. +We have spent a time making your contribution process hastle free, you just have to run the below command to get started: -3. Set up PostgreSQL databases: -```bash -createdb postgres -U postgres +#### Prerequisites -createdb nixopus_test -U postgres -``` +> [!IMPORTANT] +> As pre-requisite install Docker & Docker Compose on your machine.
+> Given `curl` by default will be available on MacOS / Linux -4. Copy and configure environment variables: +| Dependency | Installation | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **curl** | Assumed present (or install via brew/apt/dnf/yum/pacman) | +| **Docker Engine + Compose** | Manual install & ensure daemon is running | +| **Go (v1.23.4+)** | `setup.sh` auto-installs (brew on macOS; apt/dnf/yum/pacman on Linux) | +| **git** | `setup.sh` auto-installs (same mechanisms as Go) | +| **node & npm** | `setup.sh` auto-installs (brew on macOS; apt/dnf/yum on Linux) then uses `npm install -g yarn` | +| **yarn** | `setup.sh` auto-installs alongside node/npm | +| **SSH (openssh & ssh-keygen)** | `setup.sh` will install the client if missing (brew on macOS; apt/dnf/yum/pacman on Linux) and generate keys; on macOS you must manually enable “Remote Login.” | -```bash -cp .env.sample .env -``` +> [!CAUTION] +> Automatic setup isn’t available for Windows. This script only supports Linux and macOS.
+> Please refer to the [manual installation instructions](#manual-installation) for Windows. -5. Install project dependencies: -```bash -cd api -go mod download +#### Installation command + +> [!WARNING] +> Before running the setup script, verify that the default ports are available. If any are already in use, supply alternative port values when invoking the script. -cd ../view -yarn install +```bash +sudo bash -c "$(curl -sSL https://raw.githubusercontent.com/raghavyuva/nixopus/refs/heads/master/scripts/setup.sh)" ``` -6. Load development fixtures (optional but recommended): +**Check if ports are available:** -```bash -cd ../api + -# Load fixtures without affecting existing data -make fixtures-load -# Or for a clean slate (drops and recreates tables) -make fixtures-recreate -# Get help on fixtures commands -make fixtures-help -``` +If any of them is occupied, you will see the following output: -The fixtures system provides sample data including users, organizations, roles, permissions, and feature flags to help you get started quickly with development. +```bash +COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME +Code\x20H 91083 shravan20 61u IPv4 0xbb24848baadd8bde 0t0 TCP 127.0.0.1:8080 (LISTEN) +``` -## Running the Application +#### Using Custom Port Configurations -1. Start the API service: +You can change the port values by running the below commands: ```bash -air +sudo bash -c "$(curl -sSL \ + https://raw.githubusercontent.com/raghavyuva/nixopus/refs/heads/master/scripts/setup.sh)" \ + --api-port 8081 --view-port 7444 --db-port=5433 # each option is optional ``` +##### Default port configurations -2. Start the view service: +| **Service** | **Port** | +| -------------- | -------- | +| API Server | 8080 | +| Frontend | 7443 | +| Database | 5432 | -```bash -cd ../view -yarn dev -``` +::: -The view service uses: -- Next.js 15 with App Router -- React 19 -- Redux Toolkit for state management -- Tailwind CSS for styling -- Radix UI for accessible components (Shadcn Components) -- TypeScript for type safety -## Making Changes +::: details Manual Setup -Nixopus follows [trunk-based-development](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development) conventions. +If you prefer to set up your development environment manually, follow these step-by-step instructions: -1. Create a new branch: +#### Prerequisites +| Dependency | Installation | +|------------|--------------| +| **Docker Engine + Compose** | [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS/Windows) or [Docker Engine](https://docs.docker.com/engine/install/) (Linux) | +| **Go (v1.23.6+)** | [Official Go Downloads](https://golang.org/dl/) or [Go Installation Guide](installing_go.md) | +| **Node.js (v18+)** | [Node.js Downloads](https://nodejs.org/en/download/) or [Node Version Manager](https://github.com/nvm-sh/nvm) | +| **Yarn** | `npm install -g yarn` (after installing Node.js) | +| **Git** | [Git Downloads](https://git-scm.com/downloads) or package manager (brew/apt/dnf/yum/pacman) | + +#### Step 1: Clone the Repository ```bash -git checkout -b feature/your-feature-name +git clone https://github.com/raghavyuva/nixopus.git +cd nixopus ``` -2. Make your changes following the project structure: - - Place new features under `api/internal/features/` - - Add tests for new functionality - - Update migrations if needed - - Follow existing patterns for controllers, services, and storage - - For frontend changes, follow the Next.js app directory structure +#### Step 2: Configure Environment Variables +```bash +cp .env.sample .env +cp view/.env.sample view/.env +cp api/.env.sample api/.env +``` +if you want to see what each variable is for [here](#environment-variables) you can refer this guide +> [!NOTE] +> The root `.env.sample` contains combined configurations for self-hosting. For development. +> We use separate environment files for the API and frontend. -3. Run tests: +#### Step 3: Set Up PostgreSQL Database using Docker: +```bash +docker run -d \ + --name nixopus-db \ + --env-file ./api/.env \ + -p 5432:5432 \ + -v ./data:/var/lib/postgresql/data \ + postgres:14-alpine +``` +#### Step 4: Install Development Tools +Install Air for hot reloading during backend development: ```bash -cd api -make test +go install github.com/air-verse/air@latest +``` -# View linting -cd view -yarn lint +#### Step 6: Install Project Dependencies + +**Backend Dependencies:** +```bash +cd api && go mod download ``` -4. Commit your changes with clear messages. -## Submitting a Pull Request +**Frontend Dependencies:** + + -1. Push your branch and create a pull request. +#### Step 7: Load Development Fixtures (Recommended) +The fixtures system provides sample data including users, organizations, roles, permissions, and feature flags to help you get started quickly. Learn how to use fixtures in our [Development Fixtures Guide](fixtures.md). + +## Running the Application + +### Start the Backend API + +```bash +cd ../api && air +``` -2. Ensure your code: - - Follows the project structure - - Includes tests - - Updates documentation if needed - - Passes all CI checks +This will start the API server on port `8080`. If everything is set up correctly, it will automatically run database migrations. -3. Be prepared to address feedback. +Verify the server is running by visiting [`http://localhost:8080/api/v1/health`](http://localhost:8080/api/v1/health) and you should see a **success** message. -## Proposing New Features +### Start the Frontend +Open a new terminal and run: -1. Check existing issues and pull requests. + -2. Create a new issue with the `Feature request` template. +The frontend will be available at [`http://localhost:3000`](http://localhost:3000). -3. Include: - - Feature description - - Technical implementation details - - Impact on existing code +## Next Steps -## Extending Documentation +Now that you have your development environment set up, here are the next steps for contributing: -Documentation is located in the `docs/` directory. Follow the existing structure and style when adding new content. +* **Making Changes** - [Making Changes Guide](getting-involved/making-changes.md) +* **Testing Your Changes** - [Testing Guide](getting-involved/making-changes.md) +* **Submitting a Pull Request** - [Pull Request Guide](getting-involved/proposing-changes.md) +* **Proposing New Features** - [Feature Proposal Guide](getting-involved/proposing-changes.md) +* **Extending Documentation** - [Documentation Guide](documentation/documentation.md) ## Gratitude From 2ebc22bfb5e1eec0a3433a5a01c990d265ec4412 Mon Sep 17 00:00:00 2001 From: raghavyuva Date: Wed, 2 Jul 2025 09:38:02 +0530 Subject: [PATCH 4/4] fix: remove wrapped extra information in contributing guide other than manual setup flow inside a collapsible --- docs/contributing/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/contributing/index.md b/docs/contributing/index.md index 0ec83c54..900423b9 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -187,6 +187,7 @@ Open a new terminal and run: /> The frontend will be available at [`http://localhost:3000`](http://localhost:3000). +::: ## Next Steps