How to Contribute to CasaOS Development and Submit Patches: A Complete Guide

To contribute to CasaOS development, fork the IceWhaleTech/CasaOS repository, configure a Go 1.17+ and Node.js environment, develop your feature with accompanying unit tests, and submit a pull request following the project's CI and review workflow.

Contributing to CasaOS requires understanding its dual-stack architecture that combines Go-based backend services with a Node.js frontend. The official development guide in DEVELOPING.md and the contributing section of README.md outline specific workflows designed to maintain code quality across the IceWhaleTech/CasaOS repository.

Prerequisites and Development Environment Setup

Before writing code, you must configure your local environment to handle both the Go backend and the Yarn-based UI workspace.

Forking and Cloning the Repository

Start by creating a personal fork of the repository using GitHub's fork button. Then clone your fork with submodule support to ensure you capture all dependencies:

git clone --recurse-submodules --remote-submodules \
    https://github.com/<YOUR_USERNAME>/CasaOS.git
cd CasaOS

According to the development guidelines in DEVELOPING.md, the project should reside under $GOPATH/github.com/<YOUR_USERNAME>/ to maintain compatible import paths.

Installing Dependencies

CasaOS requires Go ≥ 1.17, Yarn, and Node.js. Install these via your system package manager, then initialize the frontend workspace:

cd UI
yarn install
yarn build
cd ..
go get

The UI directory operates as a separate Yarn workspace containing the frontend assets, while the root directory contains the Go modules that power the backend services.

Writing Code and Tests for CasaOS

CasaOS follows a service-oriented architecture where business logic resides in the service/ directory and HTTP handlers are defined in route/v2/.

Creating Services and Handlers

New features typically involve adding service logic in service/ and corresponding handlers. For example, to add a new greeting endpoint, create service/hello.go:

package service

import (
    "github.com/labstack/echo/v4"
)

// HelloHandler returns a friendly greeting.
func HelloHandler(c echo.Context) error {
    return c.JSON(200, map[string]string{"msg": "Hello, CasaOS!"})
}

Reference existing implementations like service/file.go to understand the project's patterns for error handling and context management.

Adding Unit Tests

Every service change requires corresponding tests. Follow the pattern established in service/file_test.go using the testify/assert package:

package service

import (
    "net/http/httptest"
    "testing"

    "github.com/labstack/echo/v4"
    "github.com/stretchr/testify/assert"
)

func TestHelloHandler(t *testing.T) {
    e := echo.New()
    req := httptest.NewRequest("GET", "/hello", nil)
    rec := httptest.NewRecorder()
    c := e.NewContext(req, rec)

    if assert.NoError(t, HelloHandler(c)) {
        assert.Equal(t, 200, rec.Code)
        assert.Contains(t, rec.Body.String(), `"msg":"Hello, CasaOS!"`)
    }
}

Run the full test suite locally to verify your changes do not break existing functionality:

go test ./...

Registering API Routes

Connect your handler to the HTTP router by modifying route/v2/route.go. The Echo framework instances defined here handle all API routing:

e.GET("/hello", service.HelloHandler)

This registration pattern mirrors existing endpoints in route/v2/file.go, ensuring consistency across the API surface.

Submitting Patches and Opening Pull Requests

Once your code passes local testing, prepare your submission for review.

Committing Changes and Pushing to Your Fork

Create a descriptive feature branch rather than committing directly to main:

git checkout -b feat/add-hello-endpoint

Write clear commit messages that describe the change scope. Then push to your fork:

git add .
git commit -m "feat: add hello endpoint for system status"
git push origin feat/add-hello-endpoint

Opening a Pull Request Against Main

Navigate to your fork on GitHub and open a pull request against IceWhaleTech/CasaOS:main. The repository includes a pull request template at .github/PULL_REQUEST_TEMPLATE.md that prompts you to:

• Describe the motivation and implementation details
• Link related issues
• Confirm that go test ./... passes locally

Responding to CI and Reviewer Feedback

The CI pipeline defined in .github/workflows/*.yml automatically executes go vet, go test, and lint checks on every pull request. If checks fail, amend your branch and push additional commits—the PR updates automatically. Maintainers may request architectural changes or additional test coverage before approving the merge.

Summary

• Fork and clone the CasaOS repository with --recurse-submodules to ensure complete dependency retrieval.
• Configure your environment with Go 1.17+, Node.js, and Yarn, building the UI workspace before running the backend.
• Develop using the service pattern in service/, following examples like service/file.go and testing with testify/assert patterns.
• Register routes in route/v2/route.go to expose new functionality through the Echo framework.
• Submit PRs against the main branch after verifying go test ./... passes and adhering to the template in .github/PULL_REQUEST_TEMPLATE.md.

Frequently Asked Questions

What are the system requirements for CasaOS development?

You need Go version 1.17 or higher, Node.js, and Yarn installed on your system. The repository must be cloned into your $GOPATH directory structure (specifically under $GOPATH/github.com/<YOUR_USERNAME>/) to satisfy Go module requirements and ensure the UI workspace builds correctly alongside the backend.

How do I run the test suite locally before submitting a patch?

Execute go test ./... from the repository root to run all Go unit tests. If you modified UI components, run the appropriate Yarn test commands within the UI/ directory. The CI pipeline also runs go vet ./... and linting checks, so verifying these locally prevents review delays.

Where should I register new API endpoints in the CasaOS codebase?

Register new HTTP handlers in route/v2/route.go using the Echo framework instance. For example, add e.GET("/hello", service.HelloHandler) alongside existing routes. This centralizes API versioning and middleware application, following the architectural pattern established in the v2 routing layer.

Does CasaOS require specific commit message formats?

While the repository follows conventional commit style (feat:, fix:, docs:), the primary requirement is clarity and specificity. Your commit message should explain what changed and why, referencing any related issues. The pull request template provides additional guidance on describing changes for the maintainers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}