diff options
Diffstat (limited to 'README.txt')
| -rw-r--r-- | README.txt | 108 |
1 files changed, 43 insertions, 65 deletions
@@ -15,85 +15,63 @@ along with this program. If not, see <https://www.gnu.org/licenses/>. STACK - Personal web services, developed and managed through a root Cargo workspace. - Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai> - GNU Affero General Public License, version 3 or later. See LICENSE. + Four services: Caddy, cgit, SearXNG, Rust private chat. + Rust management CLI; strict TypeScript browser code; GNU LibreJS checks. + SearXNG and cgit's upstream supervisor use third-party Python. No first-party Python. + License: GNU Affero General Public License, version 3 or later. See LICENSE. -GETTING STARTED +START LOCAL - Install Rust through rustup, Podman, Git, and GnuPG on a Linux development - machine, plus Node >=22.18.0 and npm for the TypeScript browser build. - Chat builds also need a GCC-compatible C compiler, Linux UAPI - headers, libclang, pkg-config, make, Perl, curl, tar, and OpenSSL 3.5+ - development libraries for native workspace checks. The pinned toolchain - includes rustfmt, Clippy, and the static x86_64 Linux target. - See docs/CHAT-PRODUCTION.txt for the native/WASI release build. - - From this directory: + Linux tools: rustup, Podman, Git, GnuPG, Node >=22.18.0, npm. + Native chat checks: GCC-compatible C compiler, Linux UAPI headers, libclang, + pkg-config, make, Perl, curl, tar, OpenSSL >=3.5 development libraries. + Pinned Rust includes rustfmt, Clippy, static x86_64 Linux target. + Native/WASI release builds: docs/CHAT-PRODUCTION.txt. cargo stack dev cargo stack status cargo stack down - Browse http://localhost:8080, /git/, /search/, and http://chat.localhost:8080/. - A fresh checkout generates a private .env automatically. - Local mode binds only loopback and does not request public certificates. - -DEVELOPMENT AND PRODUCTION - - src/main.rs forwards to the private Rust management implementation in - src/app.rs and src/app/. Future Rust application backends - belong in crates/. Add each crate to the root workspace explicitly and - inherit its strict workspace lints. - - infra/ holds service definitions, proxy configuration, container sources, - and the production user service. web/ holds the public website and WKD. - docs/ contains plaintext operations and policy documentation. + Open http://localhost:8080, /git/, /search/, http://chat.localhost:8080/. + Fresh checkout creates private .env. Local mode: loopback only, no public TLS. - The single root .env holds deployment settings and configured secrets. - The commented .env.example documents hostnames, ports, upstreams, chat, - backup recipients, and secret-setting names. See docs/CONFIGURATION.txt. - var/ contains private persistent data, container storage, temporary work, - and exports. Generated TLS private keys are runtime data under var/. - .env, var/, .tools/, target/, bin/, dist/, and node_modules/ are excluded - from Git. Browser code and tests are TypeScript; see docs/TYPESCRIPT.txt. +FILES AND STATE - The four services are Caddy, cgit, SearXNG, and the Rust chat server. The management - command is Rust. SearXNG and the cgit container's upstream supervisor retain - their third-party Python implementation. No first-party Python is needed. + Full file tree and uses: docs/MAP.txt. Rules: docs/POLICY.txt. + CLI: src/main.rs, src/app.rs, src/app/. Backends: crates/. + Add crates explicitly to root workspace; inherit strict workspace lints. + infra/: services, proxy, containers, user service. web/: site and WKD. + docs/: .txt guides. Browser code/tests: TypeScript; docs/TYPESCRIPT.txt. - Build and test on the development machine. Deploy prebuilt release - archives. The production host needs Podman, Git, and GnuPG, but no Rust - toolchain, Cargo, Node, npm, or TypeScript. + Exactly one root .env: settings and configured secrets. + One public .env.example: hosts, ports, upstreams, chat, backup keys/placeholders. + Generated databases and TLS keys: var/data. More: docs/CONFIGURATION.txt. + Git ignores .env, var/, .tools/, target/, bin/, dist/, node_modules/. -CHECKS AND LICENSES +CHECK AND RELEASE cargo install --locked --version 0.20.2 cargo-deny --root .tools cargo install --locked --version 0.9.3 --features cli cargo-about --root .tools cargo stack check cargo stack release - Check builds and checks TypeScript, then runs Rust formatting, Clippy, tests, - rustdoc, cargo-deny, and cargo-about. npm development dependencies are pinned - in package-lock.json. Typed ESLint, both compiler checks, and npm audit are - included. See docs/LINTING.txt for policy choices and tested exceptions. - THIRD-PARTY-LICENSES.html is generated from Cargo.lock and about.hbs. - Human-readable license headings use GNU's names. SPDX identifiers and - original third-party legal texts retain their exact spelling. - - Detailed manual backup, recovery, deployment, and host setup instructions - are in docs/OPERATIONS.txt. Read docs/POLICY.txt before changing conventions. - -EXPERIMENTAL CHAT - - main includes the experimental Rust/WASI chat application. Start with - docs/CHAT-APPLICATION.txt for setup, protected files, tests, backup/restore, - source licensing, and security limitations. cargo stack chat --init appends - chat configuration to the existing single root .env; cargo stack chat runs - the direct local service. docs/CHAT-PRODUCTION.txt describes its packaged - HTTPS gateway, release deployment, production owner setup, and recovery. - Building a release does not activate production. - - SQLite snapshots use the bundled SQLite C library. Release scripts build - static OpenSSL against hash-verified musl headers and the Rust musl target. - Runtime binaries remain static; no compiler is required on the VPS. + Check: TypeScript build, both compilers, typed ESLint, npm audit; Rust fmt, + Clippy, tests, private rustdoc, cargo-deny, cargo-about. npm lock: package-lock.json. + Policy and tested exceptions: docs/LINTING.txt. + Cargo.lock + about.hbs generate THIRD-PARTY-LICENSES.html. + Display GNU license names; preserve exact SPDX identifiers and upstream legal text. + + Build/test locally. Deploy prebuilt archives. VPS needs Podman, Git, GnuPG; + no Rust/Cargo/Node/npm/TypeScript. Backup, restore, host setup, deployment: + docs/OPERATIONS.txt. Building a release does not activate production. + +CHAT — EXPERIMENTAL + + cargo stack chat --init + cargo stack chat + + --init adds settings to existing root .env; chat starts direct local service. + Setup, protected files, tests, recovery, licensing, limits: docs/CHAT-APPLICATION.txt. + Packaged HTTPS, owner setup, recovery: docs/CHAT-PRODUCTION.txt. + SQLite snapshots use bundled SQLite C library. Static releases use OpenSSL, + hash-verified musl headers, Rust musl target. VPS needs no compiler. |