https://github.com/xfyyzy/soffio
Rust-native publishing platform pairing statically rendered public pages with a productivity-focused admin experience.
https://github.com/xfyyzy/soffio
ai-agents askama blog cms datastar docker-compose headless-cms musl rust soffio ssr
Last synced: 3 months ago
JSON representation
Rust-native publishing platform pairing statically rendered public pages with a productivity-focused admin experience.
- Host: GitHub
- URL: https://github.com/xfyyzy/soffio
- Owner: xfyyzy
- License: bsd-2-clause
- Created: 2025-11-05T01:30:34.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T08:11:30.000Z (3 months ago)
- Last Synced: 2026-03-25T10:08:53.234Z (3 months ago)
- Topics: ai-agents, askama, blog, cms, datastar, docker-compose, headless-cms, musl, rust, soffio, ssr
- Language: Rust
- Homepage: https://soffio.xfyyzy.xyz
- Size: 2.51 MB
- Stars: 13
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Soffio
[](https://github.com/xfyyzy/soffio/actions/workflows/ci.yml)
[](https://github.com/xfyyzy/soffio/actions/workflows/release.yml)
[](https://doc.rust-lang.org/edition-guide/)
[](https://soffio.xfyyzy.xyz)
[](https://admin.soffio.xfyyzy.xyz)
[](https://deepwiki.com/xfyyzy/soffio)
English | [中文](README.zh.md)
Soffio is a Rust-powered publishing platform. The public site renders posts statically and sprinkles interactive widgets, while the admin console focuses on writing, editing, and releasing content. The stack centers on Axum, Askama, and SQLx, and the codebase enforces a domain/application/infra layering model (see `AGENTS.md`). Soffio is released under the BSD-2-Clause license.
## Demo Environments
- Public site:
- Admin site:
The demo database resets at the top of every hour.
## Repository Layout
```
src/
├── domain # domain entities, invariants, value objects
├── application # use-case services, repo traits, job scheduling
├── infra # Postgres repos, HTTP adapters, telemetry
├── presentation # view models, templates, layouts
├── util # supporting utilities (time zones, ids, etc.)
└── main.rs # CLI / service entry point
```
## Prerequisites
- Rust stable ≥ 1.91 (2024 Edition ready)
- PostgreSQL 18 (default DSN `postgres://soffio:soffio_local_dev@localhost:5432/soffio_dev`)
- TypeScript Compiler 6.x (`tsc --version`, validated with 6.0.2)
## Quick Start
1. Install the prerequisites above and create the `soffio_dev` database.
2. Launch the service:
```bash
SOFFIO__DATABASE__URL=postgres://soffio:soffio_local_dev@localhost:5432/soffio_dev cargo run --bin soffio
```
3. Browse the defaults:
- Public site at `http://127.0.0.1:3000`
- Admin site at `http://127.0.0.1:3001`
- Override addresses via CLI flags or environment variables when needed.
## Runtime Components
- **HTTP services** — Axum 0.8 with separate listeners for public and admin traffic (`src/infra/http/public.rs` and `src/infra/http/admin/`).
- **Database access** — SQLx (Postgres); concrete repos live in `src/infra/db`, while traits are defined in `src/application/repos.rs`.
- **Telemetry** — `tracing` + `tracing-subscriber`, bootstrapped via `src/infra/telemetry.rs`.
## Headless API
- Base path: `/api/v1` on the public listener.
- Auth: `Authorization: Bearer ` (obtain/manage keys in the admin UI under “API keys”; keys are shown once). Admin workflow documented in [`docs/admin/api-keys.md`](docs/admin/api-keys.md).
- Scopes control access (snake_case): `post_read`, `post_write`, `page_read`, `page_write`, `tag_read`, `tag_write`, `navigation_read`, `navigation_write`, `upload_read`, `upload_write`, `settings_read`, `settings_write`, `job_read`, `audit_read`.
- Rate limit: configured via `api_rate_limit` (default: 120 requests per 60s per key).
- Specification: [`docs/api/openapi.yaml`](docs/api/openapi.yaml).
## soffio-cli
Headless API CLI for admins and automation. See [`docs/cli.md`](docs/cli.md) for the generated command matrix and full usage guide.
Quick start:
```
cargo build -p soffio-cli --release
SOFFIO_SITE_URL=https://your.site \
SOFFIO_API_KEY_FILE=~/.config/soffio/key \
./target/release/soffio-cli api-keys me
```
Create a post from files:
```
./target/release/soffio-cli posts create \
--title "Title" --excerpt "Summary" \
--body-file ./post.md --summary-file ./post.summary.md \
--status published
```
## Development Workflow
1. Run the baseline quality gates:
```bash
# point DATABASE_URL to your writable instance; SQLX_TEST_DATABASE_URL is used by `#[sqlx::test]` to create temp DBs
export DATABASE_URL=postgres://soffio:soffio_local_dev@localhost:5432/soffio_dev
export SQLX_TEST_DATABASE_URL=postgres://soffio:soffio_local_dev@127.0.0.1:5432/postgres
# default fast loop
./scripts/gate-fast.sh
# before PR/merge
./scripts/gate-full.sh
# periodic dependency hygiene (for example weekly)
./scripts/gate-hygiene.sh
```
2. Consult `CONTRIBUTING.md` for branching strategy, commit format, and review expectations.
3. Follow `.github/PULL_REQUEST_TEMPLATE.md` and ensure CI stays green before merging.
## Deployment
Production deployments are typically containerized. Refer to [`docs/deploy/docker.md`](docs/deploy/docker.md) for compose files, environment variables, health checks, and operational tips.
## Releases & Changelog
- Every tagged release is documented in `CHANGELOG.md`.
- Each release should ship with:
1. Migration scripts plus backward-compatibility notes.
2. A list of new/changed configuration keys and their defaults.
## Support, Community & Security
- Support channels and FAQs: `SUPPORT.md`
- Security disclosure process: `SECURITY.md`
- Code of Conduct: `CODE_OF_CONDUCT.md`
## License
BSD-2-Clause — see `LICENSE` for the full text.