🚀 Eggscape Build Server

Centralized build orchestration server with web UI

Version 1.0.0

📋 What Is This?

A web-based build orchestration system for Unity projects. Agents register themselves, and you configure everything from the web UI.

Architecture

┌────────────────────────────────────────────────┐
│         WEB BROWSER                             │
│      http://buildserver:5000                    │
│                                                 │
│  Pages:                                        │
│  - Dashboard (view all agents + jobs)          │
│  - Agents (configure agents)                   │
│  - Jobs (create/monitor jobs)                  │
│  - Settings (Git, Unity paths, etc.)           │
└─────────────────┬──────────────────────────────┘
                  │ HTTP/SignalR
                  ↓
┌────────────────────────────────────────────────┐
│      BUILD SERVER (ASP.NET + Blazor)           │
│                                                │
│  - REST API                                    │
│  - SignalR Hub (real-time)                     │
│  - SQLite Database                              │
│  - Web UI (Blazor Server)                      │
└─────────────────┬──────────────────────────────┘
                  │ HTTP (polling)
                  ↓
┌────────────────────────────────────────────────┐
│      LOCAL AGENT (Windows Service)             │
│                                                │
│  - Registers with server on startup            │
│  - Polls for jobs every 2 seconds             │
│  - Downloads config from server                │
│  - Launches Unity                              │
│  - Reports progress                            │
└─────────────────┬──────────────────────────────┘
                  │ Process
                  ↓
┌────────────────────────────────────────────────┐
│      UNITY EDITOR + BUILD AGENT                │
│                                                │
│  - Executes builds via Build Wizard            │
└────────────────────────────────────────────────┘

🎯 Key Features

For Users (Web UI)

✅ Dashboard - See all agents and jobs at a glance ✅ Agent Management - Register, configure, enable/disable agents ✅ Job Creation - Create builds with web forms ✅ Real-time Progress - Watch builds in real-time (SignalR) ✅ Build History - View past builds and download artifacts ✅ Configuration - All settings via web (no more manual config files!)

For Agents

✅ Auto-registration - Agent registers itself on startup ✅ Auto-configuration - Downloads config from server ✅ Heartbeat - Reports status every 5 seconds ✅ Job polling - Checks for new jobs every 2 seconds ✅ Progress reporting - Sends updates in real-time

📦 Project Structure

build-server/
├── BuildServer/                     # Main ASP.NET + Blazor project
│   │
│   ├── Models/                      # Data models
│   │   ├── Agent.cs                 # Agent model
│   │   ├── Job.cs                   # Job model
│   │   ├── Build.cs                 # Build result model
│   │   └── AgentConfiguration.cs    # Agent config model
│   │
│   ├── Data/                        # Database
│   │   ├── BuildServerContext.cs    # EF Core context
│   │   └── Migrations/              # EF migrations
│   │
│   ├── Controllers/                 # REST API
│   │   ├── AgentsController.cs      # Agent endpoints
│   │   ├── JobsController.cs        # Job endpoints
│   │   └── ConfigController.cs      # Configuration endpoints
│   │
│   ├── Hubs/                        # SignalR
│   │   └── BuildHub.cs              # Real-time updates
│   │
│   ├── Services/                    # Business logic
│   │   ├── AgentService.cs          # Agent management
│   │   ├── JobQueueService.cs       # Job scheduling
│   │   └── ConfigService.cs         # Configuration management
│   │
│   ├── Pages/                       # Blazor pages (WEB UI)
│   │   ├── Index.razor              # Dashboard
│   │   ├── Agents.razor             # Agent list + config
│   │   ├── Jobs.razor               # Job creation + monitoring
│   │   ├── Builds.razor             # Build history
│   │   └── Settings.razor           # Global settings
│   │
│   ├── Shared/                      # Shared components
│   │   ├── MainLayout.razor         # Layout
│   │   └── NavMenu.razor            # Navigation
│   │
│   ├── wwwroot/                     # Static files
│   │   ├── css/                     # Styles
│   │   └── js/                      # JavaScript
│   │
│   ├── appsettings.json             # Configuration
│   ├── Program.cs                   # Entry point
│   └── BuildServer.csproj           # Project file
│
├── .gitignore                       # Git ignore
├── README.md                        # This file
└── LICENSE                          # License

🚀 Quick Start

Prerequisites

.NET 6 SDK
Windows/Linux/Mac (server can run anywhere)

1. Clone & Build

git clone https://github.com/Eggscape3DAR/build-server.git
cd build-server/BuildServer
dotnet restore
dotnet build

2. Run Server

dotnet run

Server starts at: http://localhost:5000

3. Open Web UI

Open browser: http://localhost:5000

You'll see:

Dashboard (no agents yet)
Agents page (empty)
Jobs page (no jobs yet)

4. Install Agent

On build machines:

Download installer from: http://localhost:5000/download/installer
Run installer
Enter server URL: http://localhost:5000
Agent auto-registers and appears in web UI!

5. Configure Agent (from Web UI!)

Go to Agents page
Click on your agent
Configure:
- Unity project path
- Git credentials
- Repository URL
- Workspace path
- Artifacts path
Click Save

Agent downloads config automatically!

6. Create Job (from Web UI!)

Go to Jobs page
Click New Job
Fill form:
- Profile (Android Dev APK, etc.)
- Platform
- Channel
- Branch
Click Create

Job assigned to available agent automatically!

7. Watch Progress (Real-time!)

Dashboard shows live progress
SignalR updates every second
See build status, progress bar, current step

🛠️ API Endpoints

Agent Endpoints

POST /api/agents/register
POST /api/agents/heartbeat
GET  /api/agents
GET  /api/agents/{id}
PUT  /api/agents/{id}
DELETE /api/agents/{id}

Job Endpoints

POST /api/jobs
GET  /api/jobs
GET  /api/jobs/{id}
GET  /api/jobs/queue          # Get next job for agent
POST /api/jobs/{id}/progress  # Update progress
POST /api/jobs/{id}/complete  # Mark complete
POST /api/jobs/{id}/fail      # Mark failed

Config Endpoints

GET  /api/config/{agentId}     # Get agent config
POST /api/config/{agentId}     # Update agent config

Build Endpoints

GET  /api/builds
GET  /api/builds/{id}
GET  /api/builds/{id}/download # Download artifacts

📊 Database Schema

Agents Table

CREATE TABLE Agents (
    Id INTEGER PRIMARY KEY,
    AgentId TEXT UNIQUE NOT NULL,
    Name TEXT NOT NULL,
    MachineName TEXT,
    IpAddress TEXT,
    IsOnline BOOLEAN DEFAULT 0,
    IsAvailable BOOLEAN DEFAULT 1,
    LastHeartbeat DATETIME,
    CurrentJobId TEXT,
    CreatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

Jobs Table

CREATE TABLE Jobs (
    Id INTEGER PRIMARY KEY,
    JobId TEXT UNIQUE NOT NULL,
    Name TEXT NOT NULL,
    ProfileName TEXT NOT NULL,
    Platform TEXT NOT NULL,
    Channel TEXT NOT NULL,
    Status TEXT NOT NULL,  -- Queued, Running, Completed, Failed
    Progress REAL DEFAULT 0,
    AssignedAgentId TEXT,
    CreatedAt DATETIME DEFAULT CURRENT_TIMESTAMP,
    StartedAt DATETIME,
    CompletedAt DATETIME,
    ErrorMessage TEXT
);

AgentConfigurations Table

CREATE TABLE AgentConfigurations (
    Id INTEGER PRIMARY KEY,
    AgentId TEXT UNIQUE NOT NULL,
    UnityProjectPath TEXT,
    GitUsername TEXT,
    GitToken TEXT,  -- Encrypted!
    RepositoryUrl TEXT,
    WorkspacePath TEXT,
    ArtifactsPath TEXT,
    UpdatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
);

Builds Table

CREATE TABLE Builds (
    Id INTEGER PRIMARY KEY,
    JobId INTEGER NOT NULL,
    BuildPath TEXT NOT NULL,
    SizeBytes INTEGER,
    Duration INTEGER,  -- seconds
    CreatedAt DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (JobId) REFERENCES Jobs(Id)
);

🔧 Configuration

appsettings.json

{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=buildserver.db"
  },
  "BuildServer": {
    "MaxJobQueueSize": 100,
    "AgentTimeoutSeconds": 30,
    "JobTimeoutMinutes": 120,
    "ArtifactsRetentionDays": 30
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

🌐 Web Pages (Blazor)

Dashboard (`Index.razor`)

Shows:

Total agents (online/offline)
Total jobs (queued/running/completed)
Recent builds
Live activity feed (SignalR)

Agents (`Agents.razor`)

List of all agents
Status indicators (online/offline/busy)
Configure button → opens config form
Enable/Disable toggle
Delete button

Jobs (`Jobs.razor`)

Create new job button → opens form
Job queue (pending jobs)
Running jobs with live progress
Recent jobs

Builds (`Builds.razor`)

Build history with filters
Download artifacts button
View logs button
Build details

Settings (`Settings.razor`)

Global settings:
- Default Unity version
- Default workspace path
- Git credentials (global)
- Build retention policy
- Notification settings

🔐 Security

Agent Authentication

Each agent gets unique AgentId on first registration
Stored in agent's local config
Required for all API calls

Git Credentials

Stored encrypted in database
Never sent to client (web UI)
Only sent to agent when needed

Future: JWT Authentication

Add user accounts
Login system
Role-based access (Admin/Builder/Viewer)

📈 Real-time Updates (SignalR)

Events

From Server to Clients:

// Agent status changed
"AgentUpdated" -> { agentId, isOnline, isAvailable }

// Job progress
"JobProgressUpdated" -> { jobId, progress, currentStep }

// Job completed
"JobCompleted" -> { jobId, success, buildPath }

// New job created
"JobCreated" -> { jobId, name }

From Clients to Server:

// Join specific job updates
"JoinJobGroup" -> { jobId }

// Leave job updates
"LeaveJobGroup" -> { jobId }

Client Usage (JavaScript)

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/hubs/build")
    .build();

connection.on("JobProgressUpdated", (data) => {
    console.log(`Job ${data.jobId}: ${data.progress * 100}%`);
    updateProgressBar(data.jobId, data.progress);
});

await connection.start();

🚀 Deployment

Development

dotnet run

Production (Linux)

# 1. Publish
dotnet publish -c Release -o /var/www/buildserver

# 2. Create systemd service
sudo nano /etc/systemd/system/buildserver.service

[Unit]
Description=Eggscape Build Server
After=network.target

[Service]
Type=notify
WorkingDirectory=/var/www/buildserver
ExecStart=/usr/bin/dotnet /var/www/buildserver/BuildServer.dll
Restart=always
RestartSec=10
SyslogIdentifier=buildserver
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

# 3. Enable and start
sudo systemctl enable buildserver
sudo systemctl start buildserver

Production (Windows)

# 1. Publish
dotnet publish -c Release -o C:\BuildServer

# 2. Install as Windows Service
sc create BuildServer binPath="C:\BuildServer\BuildServer.exe"
sc start BuildServer

📝 TODO / Roadmap

MVP (Current)

V1.1

V1.2

V2.0

🤝 Contributing

Fork the repo
Create feature branch
Commit changes
Push and create PR

📞 Support

Documentation: This README
Issues: GitHub Issues
Discussions: GitHub Discussions

📄 License

MIT License - See LICENSE file

Created: October 2025 Version: 1.0.0 Project: Eggscape Build Server Team: Eggscape + Claude

Next: Complete implementation following IMPLEMENTATION_GUIDE.md

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
BuildServer		BuildServer
.dockerignore		.dockerignore
.gitignore		.gitignore
BUILD_SERVER_DOCUMENTATION.md		BUILD_SERVER_DOCUMENTATION.md
Dockerfile		Dockerfile
GOOGLE-DRIVE-SETUP.md		GOOGLE-DRIVE-SETUP.md
QUICK_START.md		QUICK_START.md
README.md		README.md
RECENT_CHANGES.md		RECENT_CHANGES.md
SUMMARY.md		SUMMARY.md

Folders and files

Latest commit

History

Repository files navigation

🚀 Eggscape Build Server

📋 What Is This?

Architecture

🎯 Key Features

For Users (Web UI)

For Agents

📦 Project Structure

🚀 Quick Start

Prerequisites

1. Clone & Build

2. Run Server

3. Open Web UI

4. Install Agent

5. Configure Agent (from Web UI!)

6. Create Job (from Web UI!)

7. Watch Progress (Real-time!)

🛠️ API Endpoints

Agent Endpoints

Job Endpoints

Config Endpoints

Build Endpoints

📊 Database Schema

Agents Table

Jobs Table

AgentConfigurations Table

Builds Table

🔧 Configuration

appsettings.json

🌐 Web Pages (Blazor)

Dashboard (Index.razor)

Agents (Agents.razor)

Jobs (Jobs.razor)

Builds (Builds.razor)

Settings (Settings.razor)

🔐 Security

Agent Authentication

Git Credentials

Future: JWT Authentication

📈 Real-time Updates (SignalR)

Events

Client Usage (JavaScript)

🚀 Deployment

Development

Production (Linux)

Production (Windows)

📝 TODO / Roadmap

MVP (Current)

V1.1

V1.2

V2.0

🤝 Contributing

📞 Support

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Dashboard (`Index.razor`)

Agents (`Agents.razor`)

Jobs (`Jobs.razor`)

Builds (`Builds.razor`)

Settings (`Settings.razor`)

Packages