Skip to content

Commit 3905391

Browse files
strahestrahe
authored
docs: improve readme presentation
1 parent d863dfb commit 3905391

3 files changed

Lines changed: 126 additions & 33 deletions

File tree

‎README.md‎

Lines changed: 123 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,28 @@
1+
![SynapS3 dashboard](docs/assets/readme-dashboard.png)
2+
13
# SynapS3
24

3-
SynapS3 lets S3 clients use Filecoin storage.
4-
5-
> SynapS3 is a developer preview and is not ready for production use. Test with Filecoin Calibration first, and feedback is welcome.
6-
7-
## Why SynapS3
8-
9-
- Use existing S3 clients, SDKs, and tools.
10-
- Store object data through Filecoin providers.
11-
- Manage buckets, objects, settings, tasks, and health from one dashboard.
12-
13-
## Core Features
14-
15-
| Feature | Status | Note |
16-
| --- | --- | --- |
17-
| S3-compatible API | ✅ | Works with standard S3 clients and tools |
18-
| Bucket and object operations | ✅ | Create buckets; upload, list, read, and delete objects |
19-
| Multipart uploads | ✅ | S3 multipart flow for large objects |
20-
| Object versioning | ✅ | Version IDs, current versions, and delete markers |
21-
| Web dashboard | ✅ | Buckets, objects, tasks, settings, and health views |
22-
| S3 user management | ✅ | Access keys for S3 client authentication |
23-
| Filecoin storage backend | ✅ | Stores object data through Synapse providers |
24-
| Automatic provider selection | ✅ | Selects provider contexts through Synapse |
25-
| Configurable storage copies | ✅ | Global and per-bucket copy targets |
26-
| Provider-backed reads | ✅ | Reads from cache first, then provider storage |
27-
| Wallet and payment tools | ✅ | Wallet setup, Calibration funding, and USDFC deposit |
28-
| Background task management | ✅ | Task monitoring, retry, and recovery controls |
29-
| Managed provider policy | 📝 | Provider allow/deny and placement controls |
30-
| Automatic repair | 📝 | Background replica reconciliation |
31-
| One-click deployment | 📝 | Packaged deployment automation |
32-
| Production readiness | 📝 | Security and operations hardening |
5+
[![CI](https://github.com/strahe/SynapS3/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/strahe/SynapS3/actions/workflows/ci.yml)
6+
[![Package](https://img.shields.io/badge/package-ghcr.io%2Fstrahe%2Fsynaps3-blue?logo=github)](https://github.com/strahe/SynapS3/pkgs/container/synaps3)
7+
[![Go Report](https://goreportcard.com/badge/github.com/strahe/synaps3)](https://goreportcard.com/report/github.com/strahe/synaps3)
8+
[![Go Version](https://img.shields.io/github/go-mod/go-version/strahe/SynapS3?filename=go.mod)](go.mod)
9+
10+
SynapS3 is an S3-compatible gateway for storing objects on Filecoin.
11+
12+
## Highlights
13+
14+
- S3-compatible bucket and object APIs.
15+
- Object storage backed by Filecoin storage providers.
16+
- Web dashboard for buckets, objects, wallet, tasks, topology, settings, and health.
17+
- Multipart uploads for large objects.
18+
- Wallet funding, USDFC deposit, and background task controls.
3319

3420
## Quick Start
3521

36-
This Quick Start uses `docker run` for quick evaluation. For Docker Compose deployment, use the [Docker deployment guide](docs/deployment/docker.md). To compile locally, use the [source build guide](docs/deployment/source.md).
22+
Choose the path that matches how you want to run SynapS3. Each option includes the core commands; full deployment details live in the linked guides.
23+
24+
<details>
25+
<summary>Quick evaluation with docker run</summary>
3726

3827
Prerequisites:
3928

@@ -86,6 +75,109 @@ docker rm -f synaps3-test
8675
docker volume rm synaps3-test-data
8776
```
8877

78+
</details>
79+
80+
<details>
81+
<summary>Long-running deployment with Docker Compose</summary>
82+
83+
Use this flow for a single Linux host. See the [Docker deployment guide](docs/deployment/docker.md) for full deployment, upgrade, backup, and operations notes.
84+
85+
Prerequisites:
86+
87+
- [Docker Engine](https://docs.docker.com/engine/install/) with [Docker Compose v2.24 or later](https://docs.docker.com/compose/install/)
88+
- A durable local disk for the Docker volume
89+
90+
Prepare local environment overrides:
91+
92+
```bash
93+
cp .env.example .env
94+
```
95+
96+
Generate a wallet:
97+
98+
```bash
99+
docker compose run --rm synaps3 synaps3 wallet generate
100+
```
101+
102+
Copy the generated private key into `.env`, then fund the generated address on Calibration:
103+
104+
```bash
105+
docker compose run --rm synaps3 synaps3 wallet fund-testnet 0x...
106+
```
107+
108+
Start SynapS3:
109+
110+
```bash
111+
docker compose up -d
112+
docker compose logs --tail=50 synaps3
113+
```
114+
115+
Check health and deposit USDFC:
116+
117+
```bash
118+
curl http://127.0.0.1:9090/healthz
119+
docker compose exec synaps3 synaps3 --config /var/lib/synaps3/config.toml admin status
120+
docker compose exec synaps3 synaps3 --config /var/lib/synaps3/config.toml wallet deposit 2
121+
```
122+
123+
Open the dashboard at `http://127.0.0.1:9090`. If the host is remote, use an SSH tunnel:
124+
125+
```bash
126+
ssh -L 9090:127.0.0.1:9090 user@server
127+
```
128+
129+
</details>
130+
131+
<details>
132+
<summary>Build from source</summary>
133+
134+
Use this flow for local development or custom binaries. See the [source build guide](docs/deployment/source.md) for the full build and first-upload flow.
135+
136+
Prerequisites:
137+
138+
- [Go](https://go.dev/doc/install) 1.26.3 or later
139+
- [make](https://www.gnu.org/software/make/)
140+
- C toolchain for cgo, such as [gcc](https://gcc.gnu.org/install/) or [clang](https://clang.llvm.org/get_started.html)
141+
- [Node.js](https://nodejs.org/en/download) 22.12 or later
142+
- [pnpm](https://pnpm.io/installation) 11
143+
144+
Clone and build SynapS3 with the embedded dashboard:
145+
146+
```bash
147+
git clone https://github.com/strahe/SynapS3.git
148+
cd SynapS3
149+
make build
150+
```
151+
152+
Initialize local app data and generate a wallet:
153+
154+
```bash
155+
./bin/synaps3 init
156+
./bin/synaps3 wallet generate
157+
```
158+
159+
Set `filecoin.private_key` in `~/.synaps3/config.toml`, then fund the generated address on Calibration:
160+
161+
```bash
162+
./bin/synaps3 wallet fund-testnet 0x...
163+
```
164+
165+
Start SynapS3:
166+
167+
```bash
168+
./bin/synaps3 serve
169+
```
170+
171+
In another terminal, deposit USDFC before uploading:
172+
173+
```bash
174+
./bin/synaps3 wallet deposit 2
175+
```
176+
177+
Open the dashboard at `http://127.0.0.1:9090`.
178+
179+
</details>
180+
89181
## Documentation
90182

91183
- [Docker deployment](docs/deployment/docker.md)

‎docs/assets/readme-dashboard.png‎

566 KB
Loading

‎docs/deployment/source.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Use this flow for local development or when you need to build the binary yoursel
55
## Prerequisites
66

77
- [Go](https://go.dev/doc/install) 1.26.3 or later
8+
- [make](https://www.gnu.org/software/make/)
89
- C toolchain for cgo, such as [gcc](https://gcc.gnu.org/install/) or [clang](https://clang.llvm.org/get_started.html)
910
- [Node.js](https://nodejs.org/en/download) 22.12 or later
1011
- [pnpm](https://pnpm.io/installation) 11
@@ -62,7 +63,7 @@ Start SynapS3:
6263
Default endpoints:
6364

6465
- S3 API: `http://localhost:8080`
65-
- Dashboard and admin API: `http://localhost:9090`
66+
- Dashboard and admin API: `http://127.0.0.1:9090`
6667
- Runtime data: `~/.synaps3/`
6768

6869
Do not expose the dashboard and admin API directly to an untrusted network.
@@ -97,6 +98,6 @@ Check health and task recovery:
9798

9899
```bash
99100
./bin/synaps3 admin status
100-
curl http://localhost:9090/healthz
101+
curl http://127.0.0.1:9090/healthz
101102
./bin/synaps3 admin task list --status exhausted --limit 100
102103
```

0 commit comments

Comments
 (0)