1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
|
Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
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.
GETTING STARTED
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:
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.
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.
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.
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.
CHECKS AND LICENSES
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.
|
