oneclickvirt/oneclickvirt repository overview

Basic Usage (without domain configuration):

docker run -d \
  --name oneclickvirt \
  -p 80:80 \
  -v oneclickvirt-data:/var/lib/mysql \
  -v oneclickvirt-storage:/app/storage \
  --restart unless-stopped \
  oneclickvirt/oneclickvirt:latest

Configure Domain Access:

If you need to configure a domain, set the FRONTEND_URL environment variable:

docker run -d \
  --name oneclickvirt \
  -p 80:80 \
  -e FRONTEND_URL="https://your-domain.com" \
  -v oneclickvirt-data:/var/lib/mysql \
  -v oneclickvirt-storage:/app/storage \
  --restart unless-stopped \
  oneclickvirt/oneclickvirt:latest

Or using GitHub Container Registry:

docker run -d \
  --name oneclickvirt \
  -p 80:80 \
  -e FRONTEND_URL="https://your-domain.com" \
  -v oneclickvirt-data:/var/lib/mysql \
  -v oneclickvirt-storage:/app/storage \
  --restart unless-stopped \
  ghcr.io/oneclickvirt/oneclickvirt:latest

Use external database for smaller image size and faster startup:

docker run -d \
  --name oneclickvirt \
  -p 80:80 \
  -e FRONTEND_URL="https://your-domain.com" \
  -e DB_HOST="your-mysql-host" \
  -e DB_PORT="3306" \
  -e DB_NAME="oneclickvirt" \
  -e DB_USER="root" \
  -e DB_PASSWORD="your-password" \
  -v oneclickvirt-storage:/app/storage \
  --restart unless-stopped \
  oneclickvirt/oneclickvirt:no-db

Environment Variables:

• FRONTEND_URL: Frontend access URL (required, supports http/https)
• DB_HOST: Database host address
• DB_PORT: Database port (default 3306)
• DB_NAME: Database name
• DB_USER: Database username
• DB_PASSWORD: Database password

The no-db image stores its runtime configuration at /app/storage/config.yaml in the oneclickvirt-storage volume. Reuse the same storage volume when updating the image or recreating the container; database settings entered on the initialization page and other system-level settings then survive replacement. Non-empty DB_* environment variables take precedence over the file, so recreations may also keep passing the same database environment. Deployments that explicitly mount /app/config.yaml continue to use that file first.

Use Docker Compose to deploy the complete development environment with one command, using multi-container deployment architecture with separate frontend, backend, and database containers:

git clone https://github.com/oneclickvirt/oneclickvirt.git
cd oneclickvirt
cat > .env << 'EOF'
MYSQL_ROOT_PASSWORD=change-this-root-password
MYSQL_PASSWORD=change-this-app-password
EOF
docker-compose up -d --build || docker compose up -d --build

Default Configuration:

• Frontend service: http://localhost:8888
• Backend API: Accessed via frontend proxy
• MariaDB database: Port 3306, database name oneclickvirt
• Database credentials: MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD from .env
• Data persistence:
  • Database data: Docker volume mysql_data
  • Application storage: ./data/app/

Initialization Configuration:

When accessing for the first time, you will enter the initialization interface. Please fill in the database configuration as follows:

• Database Host: mysql (container name, not 127.0.0.1)
• Database Port: 3306
• Database Name: oneclickvirt
• Database User: oneclickvirt
• Database Password: Use the MYSQL_PASSWORD value from .env

Custom Port (Optional):

To modify the frontend access port, edit the ports configuration in docker-compose.yaml:

services:
  web:
    ports:
      - "your-port:80"  # e.g., "80:80" or "8080:80"

Stop Services:

docker-compose down

View Logs:

docker-compose logs -f

Clean Data:

docker-compose down
rm -rf ./data

scripts/install_full.sh installs the database, reverse proxy, TLS configuration, frontend, backend, and system service in one flow. It supports MySQL-compatible local databases (MySQL or MariaDB) and Caddy, Nginx, or OpenResty.

The installer auto-detects common Linux and Unix-like targets, including Debian/Ubuntu, RHEL/CentOS/Rocky/Alma/Fedora/Amazon Linux, openSUSE/SLES, Arch/Manjaro, Alpine, and BSD package managers. It also detects systemd, OpenRC, rc.d/service, and no-init environments. On distributions where native MySQL packages are unavailable or unstable, the installer automatically falls back to MariaDB as the MySQL-compatible backend; use --no-db-fallback to disable this behavior. BSD installs require a matching release asset for the OS/architecture, otherwise use Docker/Linux or build the server from source.

The domain input auto-detects protocol prefixes: enter https://panel.example.com to auto-enable TLS, http://panel.example.com to auto-disable TLS, or a plain domain to be prompted interactively.

curl -fsSL https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/main/scripts/install_full.sh -o install_full.sh
bash install_full.sh

For non-interactive deployment:

# HTTPS with auto TLS
bash install_full.sh \
  --non-interactive \
  --domain https://panel.example.com \
  --email [email protected] \
  --db-type mariadb \
  --proxy caddy

# HTTP only, no TLS
bash install_full.sh \
  --non-interactive \
  --domain http://192.168.1.100 \
  --proxy caddy

Useful automation flags:

bash install_full.sh --version v1.2.3 --db-wait-timeout 300
bash install_full.sh --db-type mysql --no-db-fallback

The installer requires at least 10 GB of free disk space and 2 GB of combined memory and swap by default. It writes the generated database password to the final installation summary; save it before closing the terminal.

After installation, download the standard installer to manage OneClickVirt deployments that use a systemd service:

curl -fsSL https://raw.githubusercontent.com/oneclickvirt/oneclickvirt/main/scripts/install.sh -o install.sh
chmod +x install.sh

./install.sh status
./install.sh logs --lines 200
./install.sh logs --follow
./install.sh upgrade
./install.sh uninstall

uninstall removes the service, program, and web files while retaining config.yaml and storage; uninstall --purge removes the entire application directory. Neither mode removes the database, reverse proxy, or TLS certificates because other applications may share them. Non-interactive uninstall also requires --yes.

If you need to modify the source code or build custom images:

All-in-One Version (Built-in Database):

git clone https://github.com/oneclickvirt/oneclickvirt.git
cd oneclickvirt
docker build -t oneclickvirt .
docker run -d \
  --name oneclickvirt \
  -p 80:80 \
  -v oneclickvirt-data:/var/lib/mysql \
  -v oneclickvirt-storage:/app/storage \
  --restart unless-stopped \
  oneclickvirt

Docker builds embed scripts/install_agent.sh automatically. If you also want the controller image to serve local agent release archives instead of redirecting to GitHub Releases, place these files in server/assets/agent/ before docker build:

install_agent.sh
oneclickvirt-agent-linux-amd64.tar.gz
oneclickvirt-agent-linux-arm64.tar.gz

Standalone Database Version:

git clone https://github.com/oneclickvirt/oneclickvirt.git
cd oneclickvirt
docker build -f Dockerfile.no-db -t oneclickvirt:no-db .
docker run -d \
  --name oneclickvirt \
  -p 80:80 \
  -e FRONTEND_URL="https://your-domain.com" \
  -e DB_HOST="your-mysql-host" \
  -e DB_PORT="3306" \
  -e DB_NAME="oneclickvirt" \
  -e DB_USER="root" \
  -e DB_PASSWORD="your-password" \
  -v oneclickvirt-storage:/app/storage \
  --restart unless-stopped \
  oneclickvirt:no-db

When updating or recreating a no-db container, reuse the same oneclickvirt-storage volume. The runtime configuration remains at /app/storage/config.yaml, so the database does not need to be initialized again.

Direct source builds of the Go controller behave the same way: local agent assets in server/assets/agent/ are optional, and missing files fall back to the official GitHub installer/releases instead of breaking the build.

⁠Environment Requirements

• Go 1.25.0
• Node.js 22+
• MySQL 5.7+
• npm or yarn

⁠Environment Deployment

1. Build frontend

cd web
npm i
npm run serve

1. Build backend

cd server
go mod tidy
go run main.go

1. In development mode, there's no need to proxy the backend, as Vite already includes backend proxy requests.

2. Create an empty database named oneclickvirt in MySQL, and record the corresponding account and password.

3. Access the frontend address, which will automatically redirect to the initialization interface. Fill in the database information and related details, then click initialize.

4. After completing initialization, it will automatically redirect to the homepage, and you can start development and testing.

⁠Local Development

• Frontend: http://localhost:8080⁠
• Backend API: http://localhost:8888⁠
• API Documentation: http://localhost:8888/swagger/index.html⁠