NextWks/README.md

# Next Workspace (NextWks)

A self-hosted workspace platform — Google Workspace-like experience with integrated identity management, admin control plane, and a pluggable module system.

## Features

- **Workspace Launcher** — Dynamic app grid dashboard with PWA install support (desktop + mobile)
- **User Management** — SQLite-backed user CRUD with Authelia YAML synchronization
- **OIDC Authentication** — Delegated auth via Authelia (v4.38) with session cookies
- **Admin Panel** — Templ + HTMX admin UI with bearer token API
- **PWA Shell** — Manifest, service worker, offline support, install-to-desktop guide
- **Zero-CGO SQLite** — Single-binary deployment with no system dependencies
- **Pluggable Modules** — Architecture ready for drop-in apps (Office, Files, Calendar, etc.)

## Architecture

```
                    ┌──────────────────┐
                    │   Zoraxy Proxy   │
                    │  (TLS + routing) │
                    └────┬─────────┬───┘
                         │         │
            ┌────────────▼──┐  ┌──▼──────────────┐
            │   Authelia     │  │    NextWks Core  │
            │   :9091 (OIDC) │  │    :8080 (App)   │
            │                │  │                  │
            │  users_db.yml  │◄─┤  core/admin/     │
            │  config.yml    │  │  core/ui/        │
            └────────────────┘  │  core/auth/      │
                                └──────────────────┘
```

## Repository Structure

```
NextWks/
├── src/                     # Go source code (github.com/lexton-it/NextWks)
│   ├── main.go              # Entry point (-config flag)
│   ├── cmd/setupcheck/      # Path verification tool
│   └── core/
│       ├── config/          # YAML config parser
│       ├── db/              # SQLite driver + auto-migrations
│       ├── admin/           # User CRUD + Authelia sync + Templ UI
│       ├── auth/            # OIDC client + session store
│       ├── ui/              # Launcher, app grid, PWA templates
│       ├── api/             # gRPC proto definitions (future)
│       ├── modules/         # Drop-in app sources (future)
│       └── supervisor/      # Module process manager (future)
├── app/                     # Dev distribution
│   ├── core                 # Compiled binary
│   ├── config.yaml          # Dev configuration
│   ├── data/                # SQLite database (dev)
│   └── static/              # PWA assets (manifest, SW, icons)
├── scripts/
│   └── install-authelia.sh  # Authelia deployment script
├── install.sh               # Production installer
└── testdata/                # Test fixtures
```

## Quick Start

### Prerequisites

- Linux (amd64) — tested on Debian/Ubuntu, Proxmox LXC
- Go 1.22+ (installed automatically if missing)
- `git`, `curl`, `openssl` (standard tools)

### Production Install

```bash
curl -fsSL https://git.lohmar.co.uk/lexton-it/NextWks/raw/main/install.sh -o install.sh
sudo bash install.sh
```

The installer walks you through:
- Email configuration (SMTP/IMAP)
- Admin user creation
- URL setup (workspace + auth + proxy)
- All secrets auto-generated
- Authelia configuration written
- Systemd service created
- Smoke test verification

To re-run with saved answers: `sudo ./install.sh --from-env`

### Development

```bash
# Build
cd src && go build -o ../app/core .

# Run (from app/ directory)
cd ../app && ./core

# Run with custom config
./core -config /path/to/config.yaml
```

The server starts on `http://localhost:8080` with:
- **Workspace launcher**: `http://localhost:8080/` (OIDC-protected)
- **Admin panel**: `http://localhost:8080/admin` (bearer token)
- **Health API**: `http://localhost:8080/api/health`
- **Auth status**: `http://localhost:8080/auth/status`

### Production Install

```bash
# Full install (build → test → deploy → systemd → smoke test)
sudo ./install.sh
sudo ./install.sh --status
sudo ./install.sh --uninstall
sudo ./install.sh --build-only    # Compile only
sudo ./install.sh --skip-build    # Install existing binary
sudo ./install.sh --config-only   # Generate config only
sudo ./install.sh --help          # Show all options
```

### Run Tests

```bash
cd src && go test ./... -v
```

46 tests covering config parsing, SQLite operations, user CRUD, auth middleware, and YAML synchronization.

## Configuration

```yaml
# config.yaml
server:
  host: "0.0.0.0"
  port: 8080

admin:
  secret_token: "your-admin-token"   # Protects /admin/* routes

database:
  type: "sqlite"
  path: "./data/nextwks.db"

authelia:
  host: "http://127.0.0.1:9091"
  config_path: "/opt/authelia/configuration.yml"
  users_db_path: "/opt/authelia/users_database.yml"

oidc:
  client_id: "nextwks"
  redirect_url: "https://wks.lohmar.co.uk/auth/callback"
  domain: "wks.lohmar.co.uk"
```

## Admin API

Protected by `Authorization: Bearer <admin.secret_token>` header.

### List Users
```bash
curl -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:8080/admin/api/users
```

### Create User
```bash
curl -X POST http://localhost:8080/admin/api/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"username":"jdoe","display_name":"John Doe","email":"john@example.com","groups":"users"}]}'
```

### Delete User
```bash
curl -X DELETE http://localhost:8080/admin/api/users/jdoe \
  -H "Authorization: Bearer $ADMIN_TOKEN"
```

### Health Check
```bash
curl -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:8080/admin/api/health
```

## Authelia Integration

NextWks acts as a management layer for Authelia. When users are created or deleted:

1. The user is stored in NextWks' SQLite database (source of truth)
2. The user is automatically synchronized to `/opt/authelia/users_database.yml`
3. Authelia detects the file change (watch mode) and reloads

On first boot, NextWks bootstraps existing Authelia users into its database.

**OIDC**: Authelia must be configured with the `nextwks` client. See the [Authelia configuration guide](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/).

## License

MIT