Skip to content

Commit 89ebab1

Browse files
MattDHillMattDHill
committed
workflows, docs and readme
1 parent 81441e8 commit 89ebab1

File tree

7 files changed

+364
-61
lines changed

7 files changed

+364
-61
lines changed

‎.github/workflows/releaseService.yml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,11 @@ jobs:
1010
uses: start9labs/shared-workflows/.github/workflows/releaseService.yml@master
1111
with:
1212
# FREE_DISK_SPACE: true
13-
REGISTRY: ${{ vars.REGISTRY }} # Optional. Defaults to https://alpha-registry-x.start9.com
13+
REGISTRY: ${{ vars.REGISTRY }}
14+
S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }}
1415
secrets:
15-
DEV_KEY: ${{ secrets.DEV_KEY }} # Required
16+
DEV_KEY: ${{ secrets.DEV_KEY }}
17+
S3_ACCESS_KEY: ${{ secrets.S3_ACCESS_KEY }}
18+
S3_SECRET_KEY: ${{ secrets.S3_SECRET_KEY }}
1619
permissions:
1720
contents: write

‎CONTRIBUTING.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Contributing
2+
3+
## Building and Development
4+
5+
See the [StartOS Packaging Guide](https://docs.start9.com/packaging-guide/) for complete environment setup and build instructions.
6+
7+
### Quick Start
8+
9+
```bash
10+
# Install dependencies
11+
npm ci
12+
13+
# Build universal package
14+
make
15+
```

‎README.md‎

Lines changed: 293 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,301 @@
11
<p align="center">
2-
<img src="icon.png" alt="Project Logo" width="21%">
2+
<img src="icon.png" alt="Synapse Logo" width="21%">
33
</p>
44

5-
## Building from source
5+
# Synapse on StartOS
66

7-
1. Set up your [environment](https://docs.start9.com/packaging-guide/environment-setup.html).
7+
> **Upstream docs:** <https://element-hq.github.io/synapse/>
8+
>
9+
> Everything not listed in this document should behave the same as upstream
10+
> Synapse v1.144.0. If a feature, setting, or behavior is not mentioned
11+
> here, the upstream documentation is accurate and fully applicable.
812
9-
1. Clone this repository and `cd` into it.
13+
[Synapse](https://github.com/element-hq/synapse) is the battle-tested, reference implementation of the [Matrix](https://matrix.org/) protocol -- a next-generation, federated, full-featured, encrypted, independent messaging system.
1014

11-
1. run `make`.
15+
---
1216

13-
1. The resulting `.s9pk` can be side loaded into StartOS.
17+
## Table of Contents
1418

15-
For a complete list of build options, see the [docs](https://docs.start9.com/packaging-guide/building.html)
19+
- [Image and Container Runtime](#image-and-container-runtime)
20+
- [Volume and Data Layout](#volume-and-data-layout)
21+
- [Installation and First-Run Flow](#installation-and-first-run-flow)
22+
- [Configuration Management](#configuration-management)
23+
- [Network Access and Interfaces](#network-access-and-interfaces)
24+
- [Actions (StartOS UI)](#actions-startos-ui)
25+
- [Dependencies](#dependencies)
26+
- [Backups and Restore](#backups-and-restore)
27+
- [Health Checks](#health-checks)
28+
- [Limitations and Differences](#limitations-and-differences)
29+
- [What Is Unchanged from Upstream](#what-is-unchanged-from-upstream)
30+
- [Contributing](#contributing)
31+
- [Quick Reference for AI Consumers](#quick-reference-for-ai-consumers)
32+
33+
---
34+
35+
## Image and Container Runtime
36+
37+
| Property | Value |
38+
|----------|-------|
39+
| Synapse image | Custom `dockerBuild` from upstream source (workdir `./synapse`) |
40+
| Nginx image | `nginx:stable-alpine` (upstream unmodified) |
41+
| SQLite3 image | Custom `dockerBuild` (for admin password operations) |
42+
| Architectures | x86_64, aarch64 |
43+
44+
Synapse runs behind an Nginx reverse proxy. Nginx handles client requests on port 80, proxies Matrix API traffic to Synapse on port 8008, and serves the [Synapse Admin](https://github.com/etkecc/synapse-admin) dashboard on port 8080.
45+
46+
---
47+
48+
## Volume and Data Layout
49+
50+
| Volume | Mount Point | Purpose |
51+
|--------|-------------|---------|
52+
| `main` | `/data` | All Synapse data (config, database, media, keys, appservices) |
53+
54+
**Key files on the `main` volume:**
55+
56+
- `homeserver.yaml` -- primary Synapse configuration (managed by StartOS)
57+
- `homeserver.db` -- SQLite database
58+
- `homeserver.signing.key` -- server signing key (auto-generated by Synapse)
59+
- `homeserver.log.config` -- logging configuration
60+
- `media_store/` -- uploaded media files
61+
- `store.json` -- StartOS metadata (admin state, SMTP config)
62+
- `appservices/*.yaml` -- registered bridge/appservice configurations
63+
64+
---
65+
66+
## Installation and First-Run Flow
67+
68+
| Step | Upstream | StartOS |
69+
|------|----------|---------|
70+
| Generate config | `python -m synapse.app.homeserver --generate-config` | Automatic via `preInstall` |
71+
| Set server name | Edit `homeserver.yaml` | "Set Server Address/URL" action (critical task) |
72+
| Create admin user | `register_new_matrix_user` CLI | "Create Admin User" action (optional task) |
73+
74+
**Key difference:** On first install, StartOS generates the initial Synapse config automatically. You must run the "Set Server Address/URL" action (created as a critical task) to choose your permanent domain before starting. The "Create Admin User" action is created as an optional task.
75+
76+
**Warning:** The server address/URL is permanent and cannot be changed after the first start.
77+
78+
---
79+
80+
## Configuration Management
81+
82+
| Setting | Upstream Method | StartOS Method |
83+
|---------|-----------------|----------------|
84+
| `server_name` | `homeserver.yaml` | "Set Server Address/URL" action (one-time) |
85+
| `enable_registration` | `homeserver.yaml` | "Config" action |
86+
| Federation | `homeserver.yaml` listeners | "Config" action (enable/disable + domain whitelist) |
87+
| `max_upload_size` | `homeserver.yaml` | "Config" action (1-2000 MB) |
88+
| SMTP/email | `homeserver.yaml` | "Config" action (disabled/system/custom) |
89+
| Admin password | `register_new_matrix_user` | "Reset Admin Password" action |
90+
| Appservices | Manual YAML files | Register/List/Delete Appservice actions |
91+
92+
**Configuration NOT exposed on StartOS:**
93+
94+
- `log_config` -- fixed logging configuration
95+
- `database` -- always SQLite3 at `/data/homeserver.db`
96+
- `trusted_key_servers` -- defaults to `matrix.org`
97+
- `report_stats` -- always disabled
98+
- Listener bind addresses and ports
99+
100+
---
101+
102+
## Network Access and Interfaces
103+
104+
| Interface | Port | Protocol | Type | Purpose |
105+
|-----------|------|----------|------|---------|
106+
| Homeserver | 80 (nginx) | HTTP | API | Matrix client and federation API |
107+
| Admin Dashboard | 8080 (nginx) | HTTP | UI | Synapse Admin web interface |
108+
109+
Internally, Synapse listens on port 8008. Nginx proxies traffic from port 80, handles `.well-known/matrix/server` responses, and enforces `max_upload_size` on Matrix API routes.
110+
111+
**Access methods (StartOS 0.4.0):**
112+
113+
- LAN IP with unique port
114+
- `<hostname>.local` with unique port
115+
- Tor `.onion` address
116+
- Custom domains (if configured)
117+
118+
---
119+
120+
## Actions (StartOS UI)
121+
122+
### Set Server Address/URL
123+
124+
| Property | Value |
125+
|----------|-------|
126+
| ID | `set-server-name` |
127+
| Visibility | Hidden after first start |
128+
| Availability | Only when stopped |
129+
| Purpose | Choose permanent server domain (clearnet or Tor) |
130+
131+
Presents available hostnames from the homeserver interface. Sets `server_name` and `public_baseurl` in `homeserver.yaml`. **Cannot be changed after first start.**
132+
133+
### Create Admin User / Reset Admin Password
134+
135+
| Property | Value |
136+
|----------|-------|
137+
| ID | `reset-admin` |
138+
| Visibility | Enabled |
139+
| Availability | Only when running (create) / Only when stopped (reset) |
140+
| Purpose | Create or reset the admin account |
141+
142+
Generates a random 22-character password. On first use, creates the admin user via `register_new_matrix_user`. On subsequent uses, updates the password hash directly in SQLite.
143+
144+
### Config
145+
146+
| Property | Value |
147+
|----------|-------|
148+
| ID | `config` |
149+
| Visibility | Enabled |
150+
| Availability | Any status |
151+
| Purpose | Configure registration, federation, upload limits, SMTP |
152+
153+
**Settings:**
154+
155+
| Setting | Default | Description |
156+
|---------|---------|-------------|
157+
| Registration | Disabled | Allow public account creation |
158+
| Federation | Disabled | Enable/disable with optional domain whitelist |
159+
| Max Upload Size | 50 MB | File upload limit (1-2000 MB) |
160+
| SMTP | Disabled | Email notifications (disabled/system/custom) |
161+
162+
### Register Appservice
163+
164+
| Property | Value |
165+
|----------|-------|
166+
| ID | `register-appservice` |
167+
| Visibility | Enabled |
168+
| Availability | Any status |
169+
| Purpose | Register a Matrix bridge with the homeserver |
170+
171+
Accepts appservice credentials (ID, tokens, URL, namespace regex) and writes the registration YAML. Typically triggered automatically by bridge services via the exported `ensureAppserviceRegistration` API.
172+
173+
### List Appservices
174+
175+
| Property | Value |
176+
|----------|-------|
177+
| ID | `list-appservices` |
178+
| Visibility | Enabled |
179+
| Availability | Any status |
180+
| Purpose | View all registered bridges |
181+
182+
### Delete Appservice
183+
184+
| Property | Value |
185+
|----------|-------|
186+
| ID | `delete-appservice` |
187+
| Visibility | Enabled |
188+
| Availability | Any status |
189+
| Purpose | Remove a registered bridge |
190+
191+
### Create Bot User
192+
193+
| Property | Value |
194+
|----------|-------|
195+
| ID | `create-bot-user` |
196+
| Visibility | Hidden |
197+
| Availability | Only when running |
198+
| Purpose | Create non-admin bot accounts for bridge services |
199+
200+
---
201+
202+
## Dependencies
203+
204+
None. Synapse is a standalone application.
205+
206+
---
207+
208+
## Backups and Restore
209+
210+
**Included in backup:**
211+
212+
- `main` volume -- all Synapse data (config, database, media, keys, appservice registrations)
213+
214+
**Restore behavior:**
215+
216+
- All data, users, rooms, and settings are restored
217+
- Server name, keys, and admin credentials remain the same
218+
219+
---
220+
221+
## Health Checks
222+
223+
| Check | Method | Grace Period | Display |
224+
|-------|--------|--------------|---------|
225+
| Homeserver | HTTP GET `http://localhost:8008/health` | 15 seconds | "Homeserver" |
226+
| Nginx | Port listening on 80 | Default | Hidden |
227+
| Admin Dashboard | HTTP GET `http://localhost:8080` | Default | "Admin Dashboard" |
228+
229+
---
230+
231+
## Limitations and Differences
232+
233+
1. **Server name is permanent** -- once set and started, the server address/URL cannot be changed
234+
2. **SQLite only** -- does not support PostgreSQL (upstream default for large deployments)
235+
3. **Admin username fixed** -- always `admin`; only password can be changed
236+
4. **No workers** -- runs as a single monolith process (no worker-based scaling)
237+
5. **Fixed logging** -- log configuration is not user-configurable (INFO level, 100 MB rotation)
238+
6. **No direct `homeserver.yaml` editing** -- configuration is managed through StartOS actions
239+
7. **Tor federation limitations** -- `.onion` servers can only federate with other `.onion` servers
240+
241+
---
242+
243+
## What Is Unchanged from Upstream
244+
245+
- Full Matrix protocol compliance (client-server and server-server APIs)
246+
- End-to-end encryption support
247+
- Federation (when enabled)
248+
- Room creation, membership, and permissions
249+
- Media uploads and downloads
250+
- Push notifications
251+
- Account data and device management
252+
- Presence and typing indicators
253+
- All Matrix client compatibility (Element, FluffyChat, etc.)
254+
255+
---
256+
257+
## Contributing
258+
259+
See [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and development workflow.
260+
261+
---
262+
263+
## Quick Reference for AI Consumers
264+
265+
```yaml
266+
package_id: synapse
267+
upstream_version: 1.144.0
268+
images:
269+
synapse: dockerBuild (./synapse/Dockerfile)
270+
nginx: nginx:stable-alpine
271+
sqlite3: dockerBuild (./Dockerfile-sqlite)
272+
architectures: [x86_64, aarch64]
273+
volumes:
274+
main: /data
275+
ports:
276+
homeserver: 80 (nginx proxy to synapse:8008)
277+
admin: 8080 (synapse-admin dashboard)
278+
dependencies: none
279+
startos_managed_config:
280+
- server_name (one-time, permanent)
281+
- enable_registration
282+
- federation (listeners + domain whitelist)
283+
- max_upload_size
284+
- smtp
285+
actions:
286+
- set-server-name (enabled/hidden, only-stopped)
287+
- reset-admin (enabled, only-running/only-stopped)
288+
- config (enabled, any)
289+
- register-appservice (enabled, any)
290+
- list-appservices (enabled, any)
291+
- delete-appservice (enabled, any)
292+
- create-bot-user (hidden, only-running)
293+
health_checks:
294+
- http_get: /health (port 8008, 15s grace)
295+
- port_listening: 80
296+
- http_get: / (port 8080)
297+
backup_volumes:
298+
- main
299+
public_api:
300+
- ensureAppserviceRegistration (for bridge services)
301+
```

0 commit comments

Comments
 (0)