This commit is contained in:
192
README.md
Normal file
192
README.md
Normal file
@@ -0,0 +1,192 @@
|
||||
<p align="center">
|
||||
<img src="icon.png" alt="Spaces" width="180" />
|
||||
</p>
|
||||
|
||||
# Spaces on StartOS
|
||||
|
||||
> **Upstream docs:** <https://docs.spacesprotocol.org/>
|
||||
>
|
||||
> Everything not listed in this document should behave the same as upstream
|
||||
> `spaced` / `space-cli`. If a feature, setting, or behavior is not mentioned
|
||||
> here, the upstream documentation is accurate and fully applicable.
|
||||
|
||||
Spaces is a permissionless protocol for sovereign Bitcoin-anchored identities.
|
||||
This package runs the [`spaced`](https://github.com/spacesops/spaced) daemon
|
||||
against Bitcoin **mainnet** and exposes [`space-cli`](https://github.com/spacesops/spaced)
|
||||
through a browser-based terminal.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Image and Container Runtime](#image-and-container-runtime)
|
||||
- [Volume and Data Layout](#volume-and-data-layout)
|
||||
- [Installation and First-Run Flow](#installation-and-first-run-flow)
|
||||
- [Configuration Management](#configuration-management)
|
||||
- [Network Access and Interfaces](#network-access-and-interfaces)
|
||||
- [Actions](#actions)
|
||||
- [Backups and Restore](#backups-and-restore)
|
||||
- [Health Checks](#health-checks)
|
||||
- [Limitations and Differences](#limitations-and-differences)
|
||||
- [What Is Unchanged from Upstream](#what-is-unchanged-from-upstream)
|
||||
- [Quick Reference for AI Consumers](#quick-reference-for-ai-consumers)
|
||||
|
||||
---
|
||||
|
||||
## Image and Container Runtime
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Image | `docker.io/horologger/spaces` |
|
||||
| Architectures | `linux/amd64`, `linux/arm64` |
|
||||
| Entrypoint | StartOS-managed (image entrypoint is **not** used) |
|
||||
|
||||
The image bundles `spaced`, `space-cli`, `bitcoin-cli`, `gotty`, `node`, `npm`,
|
||||
`screen`, and a small shell environment. StartOS ignores the image's
|
||||
`docker_entrypoint.sh`; daemons are defined in `startos/main.ts`.
|
||||
|
||||
## Volume and Data Layout
|
||||
|
||||
| Path | Volume | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `/data` | `main` | Spaces data directory (`SPACED_DATA_DIR`), wallets, indexes, and `store.json` |
|
||||
| `/data/mainnet/.cookie` | `main` | Spaced RPC cookie (auto-generated by `spaced` at startup) |
|
||||
| `/data/store.json` | `main` | StartOS-managed credentials (web-UI password + bitcoind RPC user/password) |
|
||||
|
||||
## Installation and First-Run Flow
|
||||
|
||||
On the first install, StartOS:
|
||||
|
||||
1. Seeds `store.json.password` with a random 32-char alphanumeric admin password
|
||||
and creates a critical task that points the user at **Show Web UI Credentials**
|
||||
so the password can be copied before login.
|
||||
2. Seeds `store.json.btcAuth` with a random `spaces:<random>` RPC credential
|
||||
pair and creates a critical cross-service task on **Bitcoin** that runs
|
||||
bitcoind's `generate-rpc-dependent` action to register the credentials in
|
||||
`bitcoin.conf`.
|
||||
3. Launches `spaced` as a managed daemon (no `screen`, no shell auto-start).
|
||||
4. Launches the `gotty` web terminal once `spaced` is up.
|
||||
|
||||
The user is **not** prompted to choose a chain or RPC mode -- this package is
|
||||
mainnet-only.
|
||||
|
||||
## Configuration Management
|
||||
|
||||
| StartOS-Managed | Upstream-Managed |
|
||||
| --- | --- |
|
||||
| Web-UI username / password (`admin` + generated password) | `spaced` runtime tuning via `SPACED_*` env vars in the image |
|
||||
| Bitcoin RPC username / password (registered on bitcoind) | Wallet creation, bidding, and registration -- all driven via `space-cli` inside the terminal |
|
||||
| Chain selection (locked to `mainnet`) | `space-cli` flags and subcommands |
|
||||
| Spaced data directory and RPC bind | |
|
||||
|
||||
## Network Access and Interfaces
|
||||
|
||||
| Interface | Port | Protocol | Exposure | Notes |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Web UI (gotty terminal) | 8080 | HTTP | LAN / `.local` / Tor / clearnet (via StartOS) | Basic auth: `admin:<store.password>` |
|
||||
| Spaced RPC | 7225 | HTTP JSON-RPC | **Loopback only** | Internal use, cookie-authenticated |
|
||||
|
||||
## Actions
|
||||
|
||||
| ID | Name | Visibility | Availability | Purpose |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `reset-password` | Reset Web UI Password | Enabled | Any | Regenerates the web-UI password and restarts the terminal daemon |
|
||||
| `show-credentials` | Show Web UI Credentials | Hidden | Any | Surfaces the current `admin` username + masked password (launched by the first-install task) |
|
||||
| `set-bitcoin-rpc` | Set up Bitcoin RPC | Enabled | Any | Re-invokes bitcoind's `generate-rpc-dependent` with the stored credentials. Safe to call repeatedly. |
|
||||
| `sync-status` | Sync Status | Enabled | Only running | Runs `space-cli getserverinfo` inside the daemon container and returns the JSON output |
|
||||
| `reset-spaced-state` | Reset Spaced State | Enabled | Any | Deletes `/data/mainnet/` so spaced resyncs its index from spaces' anchor. Preserves `store.json` (passwords + RPC credentials). Use when spaced crash-loops on a stale or corrupt index. |
|
||||
|
||||
## Backups and Restore
|
||||
|
||||
`sdk.Backups.ofVolumes('main')` -- the entire `/data` volume is backed up,
|
||||
including spaced state, wallets, the block index, and `store.json`. On restore,
|
||||
the same idempotent init logic runs and reuses the existing credentials in
|
||||
`store.json`.
|
||||
|
||||
## Health Checks
|
||||
|
||||
| ID | Display | Grace period | Behaviour |
|
||||
| --- | --- | --- | --- |
|
||||
| `spaced` (daemon `ready`) | Spaced RPC | 120 s | TCP listen on `127.0.0.1:7225` |
|
||||
| `web-terminal` (daemon `ready`) | Web Interface | default | TCP listen on `0.0.0.0:8080` |
|
||||
| `sync` (standalone) | Spaced Sync | 300 s | Exec `space-cli getserverinfo`; reports `success` when `ready=true`, otherwise `loading` with progress percentage |
|
||||
|
||||
## Limitations and Differences
|
||||
|
||||
1. **Mainnet only.** Testnet, testnet4, signet, and regtest are not exposed.
|
||||
2. **The image's `docker_entrypoint.sh` is not used.** Its auto-start of
|
||||
`spaced` inside `screen` would conflict with the StartOS-managed daemon.
|
||||
3. **Web UI is a terminal, not a graphical app.** All Spaces operations happen
|
||||
via `space-cli` (aliased as `spaces` inside the shell).
|
||||
4. **Only port 8080 (gotty) is exposed.** Spaced RPC, and any other ports
|
||||
present in the image (e.g. 22253, 3000, 5173, 8081) are not bound.
|
||||
5. **Bitcoin Core 31.x is the only supported dependency.** Earlier majors are
|
||||
not allowed by the manifest version range.
|
||||
6. **The web terminal is independent of spaced.** Gotty stays reachable even
|
||||
when `spaced` is crash-looping, so you can always shell in to diagnose.
|
||||
|
||||
## What Is Unchanged from Upstream
|
||||
|
||||
- `space-cli` subcommands and flags work exactly as documented upstream.
|
||||
- `spaced` honours all `SPACED_*` environment variables not otherwise set by
|
||||
StartOS.
|
||||
- Wallet files, the spaces database, and the block index are managed by
|
||||
`spaced` itself; StartOS only provides the volume.
|
||||
- bitcoind connectivity follows the standard StartOS dependency-service model
|
||||
(`bitcoind.startos:8332`).
|
||||
|
||||
## Using the Web Terminal
|
||||
|
||||
After install:
|
||||
|
||||
1. Run the **Show Web UI Credentials** action (the install task surfaces it).
|
||||
2. Open the Web UI from the StartOS dashboard.
|
||||
3. Log in with `admin` and the displayed password.
|
||||
4. Use `spaces <subcommand>` -- it expands to
|
||||
`space-cli --chain mainnet --rpc-cookie /data/mainnet/.cookie <subcommand>`.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
spaces getserverinfo
|
||||
spaces walletcreate default
|
||||
spaces walletbalance default
|
||||
```
|
||||
|
||||
## Quick Reference for AI Consumers
|
||||
|
||||
```yaml
|
||||
package_id: spaces
|
||||
upstream_version: subspacesplus
|
||||
image: docker.io/horologger/spaces:v0.0.9s
|
||||
architectures: [x86_64, aarch64]
|
||||
volumes:
|
||||
main: /data
|
||||
ports:
|
||||
ui: 8080
|
||||
spaced_rpc: 7225 # loopback only
|
||||
dependencies:
|
||||
- bitcoind
|
||||
startos_managed_env_vars:
|
||||
- SPACED_CHAIN
|
||||
- SPACED_DATA_DIR
|
||||
- SPACED_RPC_BIND
|
||||
- SPACED_RPC_PORT
|
||||
- SPACED_RPC_URL
|
||||
- SPACED_BLOCK_INDEX
|
||||
- SPACED_BITCOIN_RPC_URL
|
||||
- SPACED_BITCOIN_RPC_USER
|
||||
- SPACED_BITCOIN_RPC_PASSWORD
|
||||
- BTC_RPC_HOST
|
||||
- BTC_RPC_PORT
|
||||
- BTC_RPC_USER
|
||||
- BTC_RPC_PASSWORD
|
||||
- APP_USER
|
||||
- APP_PASSWORD
|
||||
actions:
|
||||
- reset-password
|
||||
- show-credentials
|
||||
- set-bitcoin-rpc
|
||||
- sync-status
|
||||
- reset-spaced-state
|
||||
```
|
||||
Reference in New Issue
Block a user