Skip to content

contributing.mdx

Latest commit

 

History

History
233 lines (164 loc) · 7.18 KB

contributing.mdx

File metadata and controls

233 lines (164 loc) · 7.18 KB
title Contributing
description Set up your development environment and contribute to Nixopus.

Nixopus is open source and welcomes contributions. This guide covers how to set up the project locally, understand the architecture, and submit changes.

Project structure

nixopus/
├── api/            # Go API (Fuego framework, PostgreSQL, Redis)
├── view/           # Next.js 15 frontend (React 19, TypeScript)
├── installer/      # Self-hosting installer scripts and compose files
├── helpers/        # Caddyfile and environment config templates
├── .github/        # CI workflows (tests, releases, security)
└── .husky/         # Git hooks (formatting, commit lint, build checks)

The auth service lives in a separate repository at github.com/nixopus/auth. It runs as a Docker container during development — you don't need to clone it unless you're working on auth itself.

Prerequisites

  • Go 1.25+
  • Node.js 18+ and npm
  • Docker and Docker Compose
  • Air — Go hot-reload tool (go install github.com/air-verse/air@latest)

Setting up the development environment

1. Clone the repo

git clone https://github.com/nixopus/nixopus.git
cd nixopus

2. Start dependencies with Docker

The dev compose file runs PostgreSQL, Redis, Caddy, and the auth service. The API and frontend run locally outside Docker for hot reloading.

docker compose -f docker-compose-dev.yml up -d

This requires a root .env file. Copy the sample and fill in the required values:

cp .env.sample .env

Key variables to set:

Variable Description
AUTH_SERVICE_SECRET Shared secret between the API and auth service
DATABASE_URL PostgreSQL connection string (default from dev compose: postgres://nixopus:nixopus@localhost:5432/nixopus)
REDIS_URL Redis connection string (default: redis://localhost:6379)

3. Set up the API

cd api
cp .env.sample .env

Edit api/.env to point at the Docker services:

Variable Value
DATABASE_URL postgres://nixopus:nixopus@localhost:5432/nixopus
REDIS_URL redis://localhost:6379
AUTH_SERVICE_URL http://localhost:9090
PORT 8080
ENV development

Start the API with hot reload:

air

Or without hot reload:

make run

The API runs at http://localhost:8080.

4. Set up the frontend

cd view
npm install
cp .env.sample .env

Edit view/.env — the key variable is API_URL pointing to your local API (e.g., http://localhost:8080/api).

npm run dev

The frontend runs at http://localhost:3000 using Turbopack.

5. Install git hooks

Running npm install in view/ automatically installs Husky hooks at the repo root via the prepare script. The hooks enforce:

  • Pre-commit: go fmt and goimports on staged Go files, Prettier on staged frontend files
  • Commit message: Conventional commits format (enforced by commitlint)
  • Pre-push: Full build check for both API and frontend

How the services connect

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Frontend   │────▶│     API     │────▶│  Auth (Docker)│
│  localhost:3000   │     localhost:8080  │     localhost:9090 │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │  PostgreSQL  │  Redis  │  Caddy  │
                    │  (Docker)    │ (Docker)│ (Docker)│
                    └─────────────┘

Working on specific areas

API (Go)

The API uses the Fuego framework. Code lives in api/internal/features/ organized by domain (deploy, domains, containers, etc.).

cd api

make format    # go fmt + goimports
make test      # run unit tests
make test-all  # run all tests including integration
make build     # compile binary

Frontend (Next.js)

cd view

npm run dev      # development server with Turbopack
npm run lint     # ESLint
npm run format   # Prettier
npm run build    # production build

ESLint and Prettier configs are at view/eslint.config.mjs and view/.prettierrc.

Installer

The installer scripts are in installer/. If you're modifying the self-hosting flow:

  • nixopus.sh and get.sh are the entrypoints
  • selfhost/ contains the production Docker Compose and Caddyfile
  • test/ has installer test scripts and mocks

Auth service

The auth service is at github.com/nixopus/auth. For most contributions, you don't need to touch it — it runs as a pre-built Docker image.

If you need to work on auth locally, clone it as a sibling directory:

cd ..
git clone https://github.com/nixopus/auth.git

Then use docker-compose-staging.yml which builds auth from the local clone:

AUTH_SERVICE_PATH=../auth docker compose -f docker-compose-staging.yml up

Commit conventions

Nixopus uses Conventional Commits. The commit message format is enforced by commitlint on every commit.

type(scope): description

# Examples
feat(api): add deployment cancellation endpoint
fix(view): loading state on apps page when no apps exist
docs: update self-hosting configuration guide
refactor(api): migrate auth layer to Better Auth
test(api): add integration tests for deployment cancellation
ci: rewrite test workflow with docker-compose infrastructure
chore(release): v0.1.0-alpha.164

Types: feat, fix, docs, refactor, test, ci, chore, perf, style

Scopes (optional): api, view, installer, ci, or a specific feature area

Submitting a pull request

  1. Fork the repository and create a branch from master.
  2. Make your changes, ensuring tests pass and linting is clean.
  3. Write a clear commit message following the conventional commits format.
  4. Push your branch and open a pull request against master.
  5. Describe what your PR does and why — link to any related issues.
Run the full pre-push checks locally before submitting: 
cd api && go build . && cd ../view && npm run build

Testing your PR on a real server

When you open a PR, CI automatically builds preview Docker images and comments install instructions on the PR. You can test your changes on a VPS before merging:

curl -fsSL https://raw.githubusercontent.com/nixopus/nixopus/<your-branch>/installer/get.sh | \
  sudo bash -s -- --preview <pr-number>

Preview images are cleaned up automatically when the PR closes. See Branch Preview for details.

Getting help