spark/readme.md

# @serve.zone/spark

Spark is a Deno-powered server management agent for serve.zone hosts. It installs as a system daemon, activates Docker Swarm, schedules host/service maintenance tasks, and provides the bootstrap profiles currently used by Cloudly and Coreflow node deployments.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Current Role

Spark is intentionally small and operational. It is not a general-purpose configuration management framework; it is the serve.zone node-side utility that knows how to run itself as a daemon and keep selected Docker services moving.

The current implementation does four main things:

- Installs and updates a `smartdaemon_spark` systemd service through `@push.rocks/smartdaemon`.
- Runs in an explicit mode: `cloudly` or `coreflow-node`.
- Activates Docker Swarm through `@apiclient.xyz/docker` when daemon mode starts.
- Schedules recurring tasks with `@push.rocks/taskbuffer` for Spark updates, host package updates, and managed Docker service updates.

## Installation

Install a released binary:

```bash
curl -sSL https://code.foss.global/serve.zone/spark/raw/branch/main/install.sh | sudo bash
```

Install through the npm package wrapper with pnpm:

```bash
pnpm add --global @serve.zone/spark
```

The wrapper downloads the matching release binary for the current OS/architecture. Release builds currently target Linux x64/ARM64, macOS x64/ARM64, and Windows x64.

## Requirements

- Linux with systemd for daemon operation.
- Docker for service and Swarm management.
- Root privileges for daemon installation, Docker maintenance, package updates, and `prune`.
- Deno only when running from source.

macOS and Windows binaries are built for CLI/library availability, but the operational daemon paths are Linux/systemd oriented.

## Quick Start

Install Spark as a daemon:

```bash
sudo spark installdaemon
```

Run daemon mode with a profile:

```bash
sudo spark asdaemon --mode cloudly
```

or:

```bash
sudo spark asdaemon --mode coreflow-node
```

The selected mode is persisted in a user-home `npmextra` key/value store under the `servezone_spark` identity. Later `spark asdaemon` calls can reuse the stored mode when no `--mode` flag is provided.

Follow daemon logs:

```bash
sudo spark logs
```

## CLI Reference

```bash
spark <command> [options]
```

| Command | Purpose |
| --- | --- |
| `installdaemon` | Create, enable, and start the Spark daemon service. |
| `updatedaemon` | Reload the daemon service definition for the current Spark version. |
| `asdaemon --mode cloudly` | Run the daemon loop with the Cloudly profile. |
| `asdaemon --mode coreflow-node` | Run the daemon loop with the Coreflow node profile. |
| `logs` | Follow `journalctl -u smartdaemon_spark -f`. |
| `prune` | Stop Spark, remove Docker stacks/services/secrets, remove selected networks, prune Docker, restart Docker, and restart Spark. |

`prune` is destructive. Use it only on nodes where Spark owns the Docker runtime state or where losing all stacks, services, and secrets is intended.

## Daemon Behavior

`Spark.daemonStart()` starts two subsystems:

- `SparkServicesManager.start()` activates Docker Swarm.
- `SparkTaskManager.start()` schedules recurring maintenance tasks.

Scheduled tasks:

| Task | Schedule | Action |
| --- | --- | --- |
| `updateServices` | Every 2 minutes at second 30 | Checks managed Docker services and recreates them when images change. |
| `updateSpark` | Every minute | Checks for a newer Spark release and reloads the daemon after upgrade. |
| `updateHost` | Daily at midnight | Runs apt update/upgrade/autoremove/autoclean. |

The managed service list is populated by the selected mode before daemon startup. Service updates use Docker images, Docker secrets, and published port mappings.

## Programmatic Usage

Spark exports the main `Spark` class from `mod.ts`:

```typescript
import { Spark } from './mod.ts';

const spark = new Spark();
await spark.daemonStart();
```

The public instance exposes:

| Property | Purpose |
| --- | --- |
| `smartdaemon` | systemd service integration. |
| `sparkConfig` | persisted mode/config key-value store. |
| `sparkTaskManager` | taskbuffer scheduler and built-in maintenance tasks. |
| `sparkUpdateManager` | Docker Swarm activation and managed service update logic. |
| `sparkInfo` | package metadata lookup. |

## Development

Run from source:

```bash
deno task dev
```

Quality and build tasks:

```bash
deno task check
deno task lint
deno task fmt
deno task test
deno task compile
```

The package scripts intentionally defer to Deno tasks; `pnpm build` only reports that no Node build is needed.

Source map:

| Path | Purpose |
| --- | --- |
| `mod.ts` | CLI entry point and library export. |
| `ts/spark.cli.ts` | Command routing. |
| `ts/spark.classes.spark.ts` | Main class wiring. |
| `ts/spark.classes.updatemanager.ts` | Docker Swarm and service update manager. |
| `ts/spark.classes.taskmanager.ts` | Scheduled maintenance tasks. |
| `ts/spark.classes.config.ts` | Persisted mode/config store. |
| `scripts/compile-all.sh` | Multi-platform Deno compilation. |

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH\
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.