cyph3rasi
b4a9d82d05
Replace docker/metadata GH Action with a docker-publish.sh driven workflow (supports auto-versioning, extra tags, multi-arch builds and optional builder). Update docs and READMEs to use the updater and new publish flow. Add server-side swarm/node blocklist support and admin nodes API. Improve auth endpoints (me, logout, switch, session accounts) and support account switching. Extend bots API to support custom LLM provider and optional endpoint. Enforce node blocklist on chat send/receive, refactor link preview handling into dedicated preview modules, and enhance notifications and posts like/repost handlers to accept both signed actions and regular auth flows. Misc: remove admin update UI details, add helper libs (media previews, node-blocklist, reposts, notifications, etc.), and minor housekeeping (pyc, workflow tweaks).
248 lines
5.5 KiB
Plaintext
248 lines
5.5 KiB
Plaintext
# Quick Start with Docker
|
||
|
||
Get your Synapsis node running in under 10 minutes with Docker. This is the **recommended and easiest** way to self-host.
|
||
|
||
## Prerequisites
|
||
|
||
- A Linux server with a domain pointed to it
|
||
- A domain name pointed to your server
|
||
|
||
## Quick Start (5 Minutes)
|
||
|
||
```bash
|
||
# 1. Bootstrap the deployment directory
|
||
curl -fsSL https://synapsis.social/install.sh | bash
|
||
|
||
# 2. Review the generated config
|
||
nano /opt/synapsis/.env
|
||
|
||
# 3. Start your node
|
||
cd /opt/synapsis
|
||
docker compose up -d
|
||
```
|
||
|
||
Done! Your node is live at `https://your-domain.com` with automatic SSL.
|
||
|
||
## Existing nginx / reverse proxy host
|
||
|
||
If your server already has nginx, Traefik, or another reverse proxy using `80/443`, use proxyless mode instead:
|
||
|
||
```bash
|
||
curl -fsSL https://synapsis.social/install.sh | PROXY=none bash
|
||
nano /opt/synapsis/.env
|
||
cd /opt/synapsis
|
||
docker compose up -d
|
||
```
|
||
|
||
In `PROXY=none` mode:
|
||
|
||
- Synapsis skips the bundled Caddy service
|
||
- the app binds to `127.0.0.1:${PORT}`
|
||
- your existing reverse proxy should forward traffic to that localhost port
|
||
|
||
Example nginx upstream:
|
||
|
||
```nginx
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
}
|
||
```
|
||
|
||
## Detailed Setup
|
||
|
||
### 1. Bootstrap the Deployment Directory
|
||
|
||
```bash
|
||
curl -fsSL https://synapsis.social/install.sh | bash
|
||
```
|
||
|
||
If Docker is missing, the installer will install it for you on supported Linux hosts.
|
||
|
||
This downloads:
|
||
|
||
- `docker-compose.yml`
|
||
- `Caddyfile`
|
||
- `caddy-entrypoint.sh`
|
||
- `.env.example`
|
||
- `.env`
|
||
|
||
The installer also generates `AUTH_SECRET` and `DB_PASSWORD` if `openssl` is available.
|
||
|
||
### 2. Configure Environment
|
||
|
||
Edit `/opt/synapsis/.env` with your settings:
|
||
|
||
```bash
|
||
nano /opt/synapsis/.env
|
||
```
|
||
|
||
**Required variables:**
|
||
|
||
```env
|
||
# Your domain
|
||
DOMAIN=your-domain.com
|
||
|
||
# Admin email(s)
|
||
ADMIN_EMAILS=you@example.com
|
||
|
||
# Generate with: openssl rand -hex 32
|
||
AUTH_SECRET=your-secret-key-here
|
||
|
||
# Database password
|
||
DB_PASSWORD=your-secure-password
|
||
```
|
||
|
||
You can also set these before running the installer to prefill `.env`:
|
||
|
||
```bash
|
||
DOMAIN=your-domain.com
|
||
ADMIN_EMAILS=you@example.com
|
||
```
|
||
|
||
That’s it. Save and exit.
|
||
|
||
### 3. Start Synapsis
|
||
|
||
```bash
|
||
cd /opt/synapsis
|
||
docker compose up -d
|
||
```
|
||
|
||
This starts:
|
||
- **PostgreSQL** database
|
||
- **Synapsis** app (pre-built image from GitHub Container Registry)
|
||
- **Caddy** reverse proxy with automatic SSL
|
||
|
||
Visit `https://your-domain.com` to create your admin account.
|
||
|
||
## Storage Model
|
||
|
||
### Node installation
|
||
|
||
The node itself only needs Docker, PostgreSQL, and a domain to start.
|
||
|
||
### User media storage
|
||
|
||
At the moment, new user registration requires each account to provide **its own S3-compatible storage credentials** for media uploads. That requirement is enforced in the app today, so plan onboarding accordingly.
|
||
|
||
## Configuration Reference
|
||
|
||
### Core Variables
|
||
|
||
| Variable | Required | Description |
|
||
|----------|----------|-------------|
|
||
| `DOMAIN` | Yes | Your domain name |
|
||
| `AUTH_SECRET` | Yes | Generate with `openssl rand -hex 32` |
|
||
| `ADMIN_EMAILS` | Yes | Comma-separated admin emails |
|
||
| `DB_PASSWORD` | Yes | Database password |
|
||
|
||
### Optional Variables
|
||
|
||
| Variable | Default | Description |
|
||
|----------|---------|-------------|
|
||
| `BOT_MAX_PER_USER` | 5 | Max AI bots per user |
|
||
| `PORT` | auto | Application port. Default installs use `auto` to scan 3000-3020. In `PROXY=none` mode this is the localhost port your reverse proxy should target. |
|
||
| `NEXT_PUBLIC_NODE_DOMAIN` | `DOMAIN` | Override node domain if needed |
|
||
| `NEXT_PUBLIC_APP_URL` | Derived from domain | Public URL used by background jobs |
|
||
|
||
## Updating Synapsis
|
||
|
||
Updating is a single command:
|
||
|
||
```bash
|
||
cd /opt/synapsis
|
||
docker compose pull
|
||
docker compose up -d
|
||
```
|
||
|
||
This will:
|
||
- Pull the latest pre-built image from GitHub Container Registry
|
||
- Recreate containers if needed
|
||
- Run database migrations automatically
|
||
- Keep your data volumes intact
|
||
|
||
### Check Update Status
|
||
|
||
```bash
|
||
# See running containers
|
||
docker compose ps
|
||
|
||
# View logs
|
||
docker compose logs -f app
|
||
```
|
||
|
||
## Troubleshooting
|
||
|
||
### Container won't start
|
||
|
||
```bash
|
||
# Check logs
|
||
docker compose logs app
|
||
|
||
# Common issues:
|
||
# - Missing required env vars
|
||
# - Port 3000 already in use
|
||
```
|
||
|
||
### Database connection errors
|
||
|
||
```bash
|
||
# Check database container
|
||
docker compose logs postgres
|
||
|
||
# Verify env vars are loaded
|
||
docker compose exec app env | grep DATABASE
|
||
```
|
||
|
||
### Port already in use
|
||
|
||
If `80` or `443` is already in use, your server already has another reverse proxy bound there. Use `PROXY=none` instead of the default Caddy install:
|
||
|
||
```bash
|
||
curl -fsSL https://synapsis.social/install.sh | PROXY=none bash
|
||
```
|
||
|
||
For the application port itself, Synapsis uses `PORT=auto` by default, which automatically finds an available port between 3000-3020. If you need to use a specific port:
|
||
|
||
```bash
|
||
# Edit .env and set a specific port
|
||
PORT=3001
|
||
|
||
# Restart
|
||
docker compose down
|
||
docker compose up -d
|
||
```
|
||
|
||
### Reset everything (data loss!)
|
||
|
||
```bash
|
||
docker compose down -v # Remove containers AND volumes
|
||
docker compose up -d # Start fresh
|
||
```
|
||
|
||
### View all logs
|
||
|
||
```bash
|
||
# All services
|
||
docker compose logs -f
|
||
|
||
# Just the app
|
||
docker compose logs -f app
|
||
|
||
# Just the database
|
||
docker compose logs -f postgres
|
||
```
|
||
|
||
## Next Steps
|
||
|
||
- [Configure your node settings](/user-guide)
|
||
- [Learn about the Swarm](/swarm)
|
||
- [Learn how Synapsis differs from traditional federation](/user-guide/synapsis-difference)
|