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

> Learn to run CasaOS in development mode vs production mode. Discover differences in UI and backend builds, manual compilation, and automated installers for systemd services. Your complete guide.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/DEVELOPING.md):

```bash
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:

```bash
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`](https://github.com/IceWhaleTech/CasaOS/blob/main/DEVELOPING.md) and the `Makefile`:

```bash

# Build the binary

go build -o casa main.go

# Run the compiled binary

./casa

```

Alternatively, run directly without compiling:

```bash
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:

```bash

# 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`](https://github.com/IceWhaleTech/CasaOS/blob/main/casaos.conf) file
- Registers and starts the `casaos.service` systemd unit

### Service Management

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

```bash

# 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:

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

```

## Configuration File Differences

Configuration handling differs significantly between modes. In development, [`main/main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf) with persistent settings. The `config.InitSetup` function in [`main/main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main//etc/casaos/casaos.conf).
- **Source files** [`main/main.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/main/main.go), [`DEVELOPING.md`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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.