178 lines
8.2 KiB
Markdown
178 lines
8.2 KiB
Markdown
# Archipelago
|
|
|
|
> **Alpha testing — funds at your own risk.** Archipelago is experimental software and is not production-ready. Any funds you put on it are at your own risk. Substantial security hardening is planned before production readiness; current builds are for testing and feedback.
|
|
|
|
> Self-sovereign Bitcoin node OS and manifest-driven app platform.
|
|
|
|
Archipelago is a bootable personal server OS for Bitcoin infrastructure,
|
|
self-hosted apps, mesh communication, decentralized identity, and federation.
|
|
Apps are packaged as declarative `manifest.yml` files and run as rootless
|
|
Podman containers managed by the Rust backend.
|
|
|
|
[](https://www.debian.org/)
|
|
[](LICENSE)
|
|
[](https://www.rust-lang.org/)
|
|
[](https://vuejs.org/)
|
|
[](https://source.archipelago-foundation.org/lfg2025/archy/releases)
|
|
|
|
## Current release
|
|
|
|
The latest published pre-release is **v1.9.0-alpha**. Download the
|
|
[x86_64 server installer ISO](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso)
|
|
or read the [release notes and known limitations](https://source.archipelago-foundation.org/lfg2025/archy/releases/tag/v1.9.0-alpha).
|
|
Newer changes on `main` and private UAT deployments are not included in that
|
|
published ISO. Check the [releases page](https://source.archipelago-foundation.org/lfg2025/archy/releases)
|
|
for subsequent published installers and signed OTA artifacts.
|
|
|
|
**ngit is the canonical source contribution and review platform.** Gitea mirrors
|
|
accepted source and hosts release downloads. For Nostr-native cloning:
|
|
|
|
```
|
|
nostr://npub1w3sqdkrhn0gyuvsex32effzgnfpyde6qrrc4u467flg5e9txh4wsfn5vjg/relay.ngit.dev/archy
|
|
```
|
|
|
|
Clone with ngit, or use the Gitea mirror when you need a conventional Git
|
|
remote. Contributions should follow [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## Install on a server
|
|
|
|
Use a dedicated **x86_64 Intel/AMD server, mini PC, or PC**, an SSD, and an
|
|
8 GB or larger USB drive. For Bitcoin and multiple apps, 8 GB or more RAM and
|
|
a generously sized SSD are recommended; an unpruned Bitcoin node needs room
|
|
for the growing blockchain. Connect Ethernet and a monitor/keyboard, or use
|
|
your server's remote console and virtual installation media.
|
|
|
|
1. **Download the installer and checksum:**
|
|
- [Archipelago 1.9.0-alpha ISO](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso) (approximately 2.7 GB).
|
|
- [SHA-256 checksum](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso.sha256).
|
|
- [Signed checksum JSON](https://source.archipelago-foundation.org/lfg2025/archy/releases/download/v1.9.0-alpha/archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso.sha256.json).
|
|
2. **Verify the download.** Save the ISO and `.sha256` file together, then on
|
|
Linux run:
|
|
|
|
```bash
|
|
sha256sum --check archipelago-installer-1.9.0-alpha-unbundled-x86_64.iso.sha256
|
|
```
|
|
|
|
The result must be `OK`. This checks file integrity; the signed JSON is
|
|
provided separately for release-signature verification.
|
|
3. **Write the ISO to USB** using [Balena Etcher](https://etcher.balena.io/) or
|
|
your preferred image writer. Write the image rather than copying the ISO
|
|
into the USB filesystem. For a remotely managed server, attach the ISO as
|
|
virtual installation media instead. This is a raw `.iso`; no decompression
|
|
is needed.
|
|
4. **Boot the server from that media.** Disable Secure Boot for this installer
|
|
and follow the console installation prompts. **Installation erases the
|
|
selected target disk**, so back up its contents and check the disk selection
|
|
carefully.
|
|
5. **Remove/eject the installation media and boot from the installed disk.**
|
|
Find the server's address in your router's DHCP client list or local console,
|
|
then open `http://<server-ip>` from another device on the same network.
|
|
6. **Complete first-run setup:** create your dashboard password and follow the
|
|
onboarding wizard to choose apps and Bitcoin storage settings. The unbundled
|
|
ISO downloads app images as needed, so allow internet access for app setup.
|
|
|
|
For an existing Archipelago server, use the dashboard's **Settings** update
|
|
flow for a published OTA rather than reinstalling. See the
|
|
[user walkthrough](docs/user-walkthrough.md) for onboarding and daily use.
|
|
|
|
**This remains alpha software: funds are at your own risk, and production
|
|
security hardening is still ahead.**
|
|
|
|
## What is here
|
|
|
|
- `core/` - Rust workspace: backend API, container runtime, security, OpenWrt
|
|
helpers, and performance/resource management.
|
|
- `neode-ui/` - Vue 3 + TypeScript frontend.
|
|
- `apps/` - app manifests and custom app container sources.
|
|
- `docker/` - supporting container build contexts for UI companion surfaces.
|
|
- `image-recipe/` - bootable image/ISO build inputs.
|
|
- `Android/` - Android companion app.
|
|
- `scripts/` - development, release, deployment, and validation tooling.
|
|
- `docs/` - architecture, app packaging, operations, API, and roadmap docs.
|
|
|
|
## Platform model
|
|
|
|
Archipelago is built as a developer-ready app platform, not a fixed appliance:
|
|
|
|
- Apps are declared in `apps/<app-id>/manifest.yml`.
|
|
- The Rust parser in `core/container/src/manifest.rs` is the canonical schema.
|
|
- The orchestrator compiles manifests to rootless Podman/Quadlet runtime state.
|
|
- App data lives under `/var/lib/archipelago/<app-id>/`.
|
|
- Secrets are generated or read from `/var/lib/archipelago/secrets/` and
|
|
injected through Podman secrets rather than static environment values.
|
|
- Release and app catalogs are signed and verified against a pinned trust
|
|
anchor.
|
|
|
|
Start with:
|
|
|
|
- [Architecture](docs/architecture.md)
|
|
- [Developer Guide](docs/developer-guide.md)
|
|
- [App Developer Guide](docs/app-developer-guide.md)
|
|
- [App Manifest Spec](docs/app-manifest-spec.md)
|
|
- [Nostr Git Source Hosting Plan](docs/nostr-git-source-hosting.md)
|
|
- [Troubleshooting](docs/troubleshooting.md)
|
|
|
|
## Quick start
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
The dev UI runs at `http://localhost:8100` with a mock backend on `:5959`.
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd core
|
|
cargo build
|
|
cargo test --all-features
|
|
```
|
|
|
|
Linux is the supported backend runtime and release-build target. macOS is fine
|
|
for frontend work and many Rust compile/test loops, but host integration tests
|
|
that touch Podman, systemd, networking, or image build paths require Linux.
|
|
|
|
### App manifests
|
|
|
|
```bash
|
|
./scripts/validate-app-manifest.sh apps/filebrowser/manifest.yml
|
|
python3 scripts/generate-app-catalog.py
|
|
python3 scripts/check-app-catalog-drift.py --release --strict
|
|
```
|
|
|
|
`scripts/generate-app-catalog.py` requires Python with PyYAML installed.
|
|
|
|
## Documentation map
|
|
|
|
The full, grouped index lives at **[docs/README.md](docs/README.md)**. The most
|
|
common entry points:
|
|
|
|
| Doc | Purpose |
|
|
|-----|---------|
|
|
| [Architecture](docs/architecture.md) | System layers, crates, data paths, security model |
|
|
| [Developer Guide](docs/developer-guide.md) | Local setup, code workflow, testing |
|
|
| [API Reference](docs/api-reference.md) | JSON-RPC API overview |
|
|
| [App Developer Guide](docs/app-developer-guide.md) | How to package and test apps |
|
|
| [App Manifest Spec](docs/app-manifest-spec.md) | Manifest schema and validation rules |
|
|
| [Nostr Git Source Hosting Plan](docs/nostr-git-source-hosting.md) | ngit/NIP-34 contribution workflow and maintainer model |
|
|
| [Apps README](apps/README.md) | Packaged app catalog overview |
|
|
| [Image Recipe](image-recipe/README.md) | Bootable image build flow |
|
|
| [Roadmap](docs/ROADMAP.md) | Shipped, in-progress, and planned work |
|
|
| [Archive](docs/archive/) | Historical plans, audits, and handoffs |
|
|
|
|
## Contributing
|
|
|
|
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. For
|
|
security issues, follow [SECURITY.md](SECURITY.md) and do not open a public
|
|
issue.
|
|
|
|
## License
|
|
|
|
Archipelago is licensed under the [MIT License](LICENSE). Third-party notices
|
|
are listed in [NOTICE](NOTICE) and generated license inventories in component
|
|
release artifacts.
|