ASA Server Manager

Go package directories have been consolidated under internal/; package names and layering are unchanged (see docs/INTERNAL_LAYOUT_MIGRATION.md).

A comprehensive ARK Server Ascended (ASA) server management tool built with Go and Vue.js, featuring a command-line interface, HTTP API, and web dashboard.

Features

Core Functionality

✅ Instance Management: Create, list, rename, and delete server instances
✅ Server Control: Start, stop, and restart individual or all instances
✅ RCON Support: Send RCON commands to server instances
✅ Backup & Restore: Create and restore world backups with flexible options
✅ Configuration Management: View and edit game configuration files (Game.ini, GameUserSettings.ini)
✅ Logging: Real-time server and instance logs viewing

Advanced Features

✅ Windows Service Integration: Run as a Windows service for background operation
✅ HTTP API Server: RESTful API with WebSocket and SSE support for real-time updates
✅ Web Dashboard: Embedded Vue.js web interface for intuitive management
✅ FRP Integration: Built-in Fast Reverse Proxy management for server exposure
✅ Syncthing Integration: File synchronization capabilities for server configuration
✅ Port Management: Automatic port conflict detection and resolution

System Requirements

Operating System: Windows 10/11 (64-bit)
Go Version: 1.26 or higher (for development)
Node.js: 16.x or higher (for frontend development)
Disk Space: Minimum 20GB for server files and instances
RAM: 8GB minimum, 16GB recommended

Installation

Pre-built Binaries

Download the latest release from the Releases page
Extract the archive to your preferred location
Run asa-manager.exe to start the application

Building from Source

Backend (Go)

go mod tidy
go build -o asa-manager.exe

Frontend (Vue.js)

cd app
npm install
npm run build

Usage

Command-Line Interface

Basic Commands

# List all instances
asa-manager list

# Create a new instance
asa-manager create

# Start an instance
asa-manager start <instance_name>

# Stop an instance
asa-manager stop <instance_name>

# Restart an instance
asa-manager restart <instance_name>

# Check server status
asa-manager status [instance_name]

Backup & Restore

# Create a backup
asa-manager backup <instance_name> <world_folder>

# Restore a backup
asa-manager restore <instance_name> <backup_file> [flags]

Available restore flags:

--worldfile: Restore world file (SaveDir)
--instance-config: Restore instance_config.ini
--game-config: Restore game config files

Batch Operations

# Start all instances
asa-manager start-all

# Stop all instances
asa-manager stop-all

Configuration Management

# View Game.ini for an instance
asa-manager view-game [instance_name]

# View GameUserSettings.ini for an instance
asa-manager view-game-user-settings [instance_name]

# Synchronize game config files
asa-manager sync-config <instance_name> [instance_name2] [...]

Windows Service Management

# Install as Windows service
asa-manager service install

# Start Windows service
asa-manager service start

# Stop Windows service
asa-manager service stop

# Remove Windows service
asa-manager service remove

HTTP API Server

# Start HTTP API server (HTTPS + HTTP/2 by default)
asa-manager api

# Fall back to plain HTTP/1.1
asa-manager api --tls=false

# Use your own certificate instead of the local CA
asa-manager api --cert-file C:\certs\asa.crt --key-file C:\certs\asa.key

# Add extra names to the certificate SAN (e.g. the domain your proxy serves)
asa-manager api --tls-domains asa.example.com

The API server runs on port 19193 by default.

HTTPS & the Local CA

The server speaks HTTPS with HTTP/2 out of the box. This is not (only) about encryption: browsers negotiate HTTP/2 exclusively over TLS via ALPN, and HTTP/2 lifts the "6 connections per origin" limit that persistent SSE streams otherwise exhaust. See docs/HTTP2_CONNECTION_OPTIMIZATION.md.

On first start the program generates a local CA under {BaseDir}/certs/ and installs it into the Windows trusted root store, so https://localhost:19193 opens without any certificate warning. The CA private key is generated on your machine and is never shipped in the binary.

# Show CA fingerprint, validity and whether it is trusted
asa-manager cert status

# Install manually (--machine installs for all users, requires administrator)
asa-manager cert install [--machine]

# Remove the CA from the trusted root store
asa-manager cert uninstall

asa-manager service remove removes the CA automatically. To never touch the trusted root store, run with --tls-trust=false (the browser will then show a warning you must accept once), or turn TLS off entirely with --tls=false.

Web Dashboard

Once the HTTP API server is running, access the web dashboard at:

https://localhost:19193

The dashboard provides a user-friendly interface for:

Managing server instances
Controlling server operations
Viewing real-time logs
Editing configurations
Managing backups
Monitoring server resources

Project Structure

Directory Structure

The former asaserver god-package has been split by single responsibility into the domain packages below; pure utilities live under pkg/. See docs/PACKAGE_RESTRUCTURE_PLAN.md for the rationale.

asa-server/
├── main.go              # Entry point: CLI, GUI, Windows service detection
│
│  ── Domain packages (bottom-up, no cycles) ──
├── pkg/                 # Leaf utilities: fsutil, winproc, netutil, tail, console, iox,
│                        #   processjob (Windows Job Objects), serverinfo (gopsutil metrics)
├── config/              # Directory layout, InstanceConfig, INI read/write, config sync
├── certmgr/             # Local CA + leaf certificate, Windows trusted root store (HTTPS/h2)
├── process/             # PID store + IsServerRunning (breaks the state <-> instance cycle)
├── rconx/               # RCON connection & command execution (retries, sentinel errors)
├── realtime/            # WebSocket hub: server events + interactive RCON
├── state/               # BadgerDB instance state persistence (CAS state machine)
├── installer/           # SteamCMD download / ARK server update
├── mirror/              # Per-instance NTFS junction mirrors
├── instance/            # Lifecycle: Start/Stop/Restart, saves, mod extraction, ASA version
├── countdown/           # Delayed stop/restart orchestration: countdown + in-game announcements
├── batchmanage/         # Batch start/stop/restart across instances (see docs/BATCH_OPERATION.md)
├── schedule/            # Cron-like scheduled tasks (restart / update)
├── updatemanage/        # Server update task singleton
│
│  ── Interfaces ──
├── webapi/              # HTTP API, split by domain: instanceapi, serverapi, backupapi,
│                        #   configapi, saveapi, logapi, iconapi, apiresp
├── app/                 # Embedded Vue.js frontend (//go:embed dist)
├── gui/                 # Fyne desktop GUI (system tray, service mgmt, log viewer)
├── winservice/          # Windows service integration (kardianos/service)
├── actions/             # CLI command handlers
│
│  ── Supporting ──
├── backup/              # tar+zstd backup/restore with functional options
├── frpmanage/           # FRP reverse proxy management (embedded frpc.exe)
├── syncthingmanage/     # Syncthing file sync management (embedded syncthing.exe)
├── parseserver/         # ARK save file parsing
├── logger/              # Zap + lumberjack structured logging with rotation
└── docs/                # Documentation (see index below)

Instance Directory Structure

instances/
└── <instance_name>/
    ├── instance_config.ini    # Instance-specific configuration
    ├── Config/                # Game configuration files
    │   ├── Game.ini
    │   └── GameUserSettings.ini
    └── server.log             # Server log file

HTTP API

The HTTP API provides RESTful endpoints for all server management functions. For detailed documentation, see the API Reference.

Key API Endpoints

GET /health - Health check
GET /api/instances - List all instances
POST /api/instances - Create a new instance
GET /api/instances/:name - Get instance status
POST /api/server/:name/start - Start an instance
POST /api/server/:name/stop - Stop an instance
POST /api/rcon/:name/command - Send RCON command
GET /api/ws/events - WebSocket for real-time events
GET /api/logs/:name - SSE stream for instance logs

Configuration

Instance Configuration

Each instance has an instance_config.ini file with the following structure:

[ServerSettings]
ServerName=ARK Server <instance_name>
ServerPassword=
ServerAdminPassword=adminpassword
MaxPlayers=70
MapName=TheIsland_WP
RCONPort=27020
Port=7777
ModIDs=
CustomStartParameters=-NoBattlEye -crossplay -NoHangDetection
SaveDir=<instance_name>
ClusterID=

Integration Features

FRP Integration

The tool includes built-in FRP (Fast Reverse Proxy) management for exposing your server to the internet.

Syncthing Integration

Syncthing integration allows for easy synchronization of configuration files across multiple servers.

Development

Prerequisites

Go 1.26 or higher
Node.js 16.x or higher
npm 8.x or higher

Building the Application

Build the backend:
```
go build -o asa-manager.exe
```
Build the frontend:
```
cd app
npm install
npm run build
```

Running the Development Server

Start the API server:
```
go run main.go api
```
Start the frontend development server:
```
cd app
npm run dev
```

Adding New Features

CLI Commands: Add new commands in actions/actions.go and register them in main.go
API Endpoints: Add new endpoints in webapi/actions.go
Frontend Components: Add new components in app/src/components/
Frontend Views: Add new views in app/src/views/

Troubleshooting

Common Issues

Command Not Found

Ensure asa-manager.exe is in your PATH or run it from the correct directory.

Instance Failed to Start

Check if the instance configuration is correct
Verify that required ports are not in use
Check the server logs for more details

Backup Failed

Ensure the instance is stopped before creating a backup
Verify the world folder name is correct
Ensure there is sufficient disk space

API Server Not Accessible

Check if the service is running
Verify firewall settings allow traffic on port 19193

Documentation

All documentation lives in docs/. Start with docs/README.md for the Chinese overview, or jump straight to a topic below.

Architecture & Design

Document	What it covers
ARCHITECTURE.md	System architecture and design patterns
PACKAGE_RESTRUCTURE_PLAN.md	Splitting the `asaserver` god-package into domain packages
STATE_CONTROL.md	Instance state machine, CAS transitions, mutual exclusion
V2_MIRROR_STARTUP_ARCHITECTURE.md	NTFS junction mirrors for parallel instance startup
HTTP2_CONNECTION_OPTIMIZATION.md	HTTP/2 plan to lift the browser's 6-connection-per-origin cap on SSE
instance-manager-daemon.md	Instance manager daemon design

Features

Document	What it covers
BATCH_OPERATION.md	Batch start/stop/restart — orchestration, preflight, CAS, SSE log stream
stop-restart-countdown.md	Delayed stop/restart countdown with in-game announcements
COUNTDOWN_RCON_REFACTOR_PLAN.md	Extracting the `countdown` and `rconx` packages
SCHEDULE_RUN_LOG_DESIGN.md	Scheduled tasks and their run logs
ARK_SAVE_PARSE_SOLUTION.md	ARK save file parsing
PARSESERVER_REDESIGN.md	`parseserver` redesign
state-change-ws-push.md	Pushing state changes over WebSocket
ws-state-push-refactor.md	WebSocket state push refactor
VirtualLogList.md	Virtualized log list (frontend)

Reference

Document	What it covers
API_REFERENCE.md	Complete HTTP API reference
CHEATSHEET.md	Commands, config, and RCON quick reference
asa-server-configuration.md	ARK server configuration reference
asa-game-configuration-reference.md	Game.ini / GameUserSettings.ini reference
game-ini-visual-config-guide.md	Visual guide to Game.ini options
asa-creatureids.md · asa-itemsids.md · asa-engrams.md	Creature / item / engram ID tables

Migration & History

Document	What it covers
MIGRATION.md	Migrating from the old bash scripts
V2_MIGRATION_PLAN.md · V2_MIGRATION_CHANGELOG.md	v2 migration plan and changelog
STARTUP_FIXES.md	Startup/shutdown fixes log

Tooling

Document	What it covers
ark-translation-tool.md	ARK translation tool
download-creature-icons.md · download-item-icons.md	Icon download scripts

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

Support

For issues and feature requests, please create a new GitHub Issue.

Name		Name	Last commit message	Last commit date
.mimocode/plans		.mimocode/plans
app		app
data/ark-translation		data/ark-translation
docs		docs
icon		icon
internal		internal
pkg		pkg
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
README_zh.md		README_zh.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
openapi.json		openapi.json

Latest commit

History

Folders and files

Repository files navigation

ASA Server Manager

Features

Core Functionality

Advanced Features

System Requirements

Installation

Pre-built Binaries

Building from Source

Backend (Go)

Frontend (Vue.js)

Usage

Command-Line Interface

Basic Commands

Backup & Restore

Batch Operations

Configuration Management

Windows Service Management

HTTP API Server

HTTPS & the Local CA

Web Dashboard

Project Structure

Directory Structure

Instance Directory Structure

HTTP API

Key API Endpoints

Configuration

Instance Configuration

Integration Features

FRP Integration

Syncthing Integration

Development

Prerequisites

Building the Application

Running the Development Server

Adding New Features

Troubleshooting

Common Issues

Command Not Found

Instance Failed to Start

Backup Failed

API Server Not Accessible

Documentation

Architecture & Design

Features

Reference

Migration & History

Tooling

Contributing

License

Support

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages