How to Run CasaOS in Development Mode vs Production Mode: A Complete Guide

CasaOS uses the same binary for both development and production, but development mode requires manually building the UI and Go backend from source, while production mode deploys via an automated installer that configures CasaOS as a systemd service.

CasaOS, maintained by IceWhaleTech, is an open-source home cloud system that supports two distinct runtime contexts. Whether you are contributing code to the repository or deploying a stable server environment, understanding how to run CasaOS in development mode versus production mode ensures optimal performance and workflow efficiency.

Understanding the Runtime Architecture

The CasaOS architecture does not rely on separate binaries for different environments. According to the source code in main/main.go, the application entry point loads configuration via config.InitSetup and starts the HTTP server regardless of how it is invoked. The distinction between modes lies entirely in the build process, installation location, and execution context.

Development Mode Setup

Development mode prioritizes fast iteration and code modification. This workflow involves cloning the repository, building the UI submodule, and compiling the Go backend manually.

Prerequisites and Repository Setup

Before building, ensure you have Go 1.17 or later, Node.js, and Yarn installed. Clone the repository including the CasaOS-UI submodule as documented in DEVELOPING.md:

git clone --recurse-submodules https://github.com/IceWhaleTech/CasaOS.git
cd CasaOS

Building the Frontend

The UI resides in the CasaOS-UI submodule. Navigate to it and install dependencies before building the production assets:

cd CasaOS-UI
yarn install
yarn build
cd ..

For active development with hot-reloading, use yarn dev instead of yarn build.

Compiling and Running the Backend

From the repository root, compile the Go binary using the commands specified in DEVELOPING.md and the Makefile:

# Build the binary

go build -o casa main.go

# Run the compiled binary

./casa

Alternatively, run directly without compiling:

go run .

By default, this uses the embedded casaos.conf.sample configuration. You can override this with the -c flag to specify a custom configuration path.

Production Mode Deployment

Production mode delivers a stable, system-managed installation intended for live servers. This method uses pre-built binaries and registers CasaOS as a systemd service.

Official One-Liner Installation

The recommended production deployment uses the official install script documented in the README:

# Using wget

wget -qO- https://get.casaos.io | sudo bash

# Or using curl

curl -fsSL https://get.casaos.io | sudo bash

This script automatically:

• Downloads the pre-compiled binary to /usr/local/bin/casaos
• Creates the configuration directory at /etc/casaos/
• Writes the permanent casaos.conf file
• Registers and starts the casaos.service systemd unit

Service Management

After installation, manage the CasaOS service using standard systemd commands:

# Check service status

systemctl status casaos

# Start the service

systemctl start casaos

# Enable auto-start on boot

systemctl enable casaos

To upgrade an existing production installation, use the update script:

wget -qO- https://get.casaos.io/update | sudo bash

Configuration File Differences

Configuration handling differs significantly between modes. In development, main/main.go loads the embedded sample configuration (_confSample) by default, allowing immediate execution without external config files.

In production, the installer generates /etc/casaos/casaos.conf with persistent settings. The config.InitSetup function in main/main.go processes these configurations identically, but production environments typically require the -c flag pointing to the system configuration path.

Build Automation Reference

The repository includes a Makefile that formalizes the development build process. Key targets include:

• make build-ui: Executes yarn install && yarn build in the CasaOS-UI submodule
• make build-backend: Compiles the Go binary

These targets ensure consistent builds across development environments and serve as the foundation for the production release pipeline.

Summary

• CasaOS uses the same binary for both development and production; the difference lies in build methodology and execution context.
• Development mode requires manual cloning, UI building with Yarn, and Go compilation via go build or go run . as documented in DEVELOPING.md.
• Production mode deploys via the one-liner installer at get.casaos.io, which installs to /usr/local/bin/casaos and configures a systemd service.
• Configuration in development uses the embedded sample file, while production writes to /etc/casaos/casaos.conf.
• Source files main/main.go, DEVELOPING.md, and the Makefile contain the definitive implementation details for both modes.

Frequently Asked Questions

What is the difference between running go run . and using the production installer?

Running go run . executes CasaOS directly from source code using the embedded sample configuration, ideal for development. The production installer downloads a pre-compiled binary, installs it to /usr/local/bin/casaos, and configures it as a persistent systemd service with proper logging and auto-start capabilities.

Can I use the production binary for development testing?

Yes. You can build the production binary locally using go build -o casa main.go and run it manually with ./casa. This executes the same code as the installed production version, but without systemd management, allowing you to test configuration changes and debug startup behavior.

Where does CasaOS look for configuration files in development mode?

In development mode, main/main.go initializes configuration via config.InitSetup using the embedded casaos.conf.sample by default. You can specify a custom configuration file using the -c flag followed by the path to your configuration file.

How do I rebuild the CasaOS UI after making changes in development?

After modifying files in the CasaOS-UI submodule, rebuild the frontend by running yarn install && yarn build within that directory. For active development with hot-reloading, use yarn dev instead. The Makefile target build-ui automates this process.

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