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. The pinned toolchain includes rustfmt, Clippy, and the static
    x86_64 Linux target.

    From this directory:

        cargo stack dev
        cargo stack status
        cargo stack down

    Browse http://localhost:8080, /git/, and /search/.
    A fresh checkout generates a private .env automatically.
    Local mode binds only loopback and does not request public certificates.

DEVELOPMENT AND PRODUCTION

    src/ holds the Rust management command. 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.

    Only .env holds configured secrets. .env.example documents the keys.
    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/, and dist/ are excluded from Git.

    The three existing services are Caddy, cgit, and SearXNG. 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, Compose, or Docker daemon.

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 runs formatting, Clippy, tests, rustdoc, cargo-deny, and cargo-about.
    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.