From bf42c1b56b40934d686dfcf19b5c223974e5fda2 Mon Sep 17 00:00:00 2001 From: Andy Brown Date: Mon, 9 Mar 2026 17:54:33 +0000 Subject: [PATCH] docs: add in-repository documentation in doc/ and link from README Add doc/README.md (index), doc/architecture.md, doc/development.md, doc/configuration.md. Update README.md to link to doc/ and to docs.rustfs.com; fix CONTRIBUTING.md development guide link to doc/development.md. Creation metadata (extended description): - Created by: Cursor AI assistant (Auto / agent router). - Cost: Not available in this context; check Cursor session usage or billing for token/API cost of this edit session. Made-with: Cursor --- CONTRIBUTING.md | 2 +- README.md | 4 ++- doc/README.md | 18 +++++++++++++ doc/architecture.md | 35 ++++++++++++++++++++++++ doc/configuration.md | 24 +++++++++++++++++ doc/development.md | 64 ++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 145 insertions(+), 2 deletions(-) create mode 100644 doc/README.md create mode 100644 doc/architecture.md create mode 100644 doc/configuration.md create mode 100644 doc/development.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07bc90010b..dc07fbf191 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## 📋 Code Quality Requirements -For instructions on setting up and running the local development environment, please see [Development Guide](docs/DEVELOPMENT.md). +For instructions on setting up and running the local development environment, please see [Development Guide](doc/development.md). ### 🔧 Code Formatting Rules diff --git a/README.md b/README.md index e62aab8342..d868e55f4d 100644 --- a/README.md +++ b/README.md @@ -208,7 +208,8 @@ nix run ## Documentation -For detailed documentation, including configuration options, API references, and advanced usage, please visit our [Documentation](https://docs.rustfs.com). +- **[In-repository docs](doc/)** — Architecture, development guide, and configuration overview (this repo). +- **[RustFS Documentation](https://docs.rustfs.com)** — Full manual, installation, configuration options, API reference, and advanced usage. ## Getting Help @@ -220,6 +221,7 @@ If you have any questions or need assistance: ## Links +- [In-repository documentation](doc/) - Architecture, development, and configuration (this repo) - [Documentation](https://docs.rustfs.com) - The manual you should read - [Changelog](https://github.com/rustfs/rustfs/releases) - What we broke and fixed - [GitHub Discussions](https://github.com/rustfs/rustfs/discussions) - Where the community lives diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000000..058c65383f --- /dev/null +++ b/doc/README.md @@ -0,0 +1,18 @@ +# RustFS Project Documentation + +This folder contains in-repository documentation for the RustFS project. For the full user manual, installation, and API reference, see the official [RustFS Documentation](https://docs.rustfs.com). + +## Contents + +| Document | Description | +|----------|-------------| +| [Architecture](architecture.md) | High-level design, components, and workspace layout | +| [Development](development.md) | Building, testing, and contributing (Make targets, pre-commit) | +| [Configuration](configuration.md) | Configuration overview and environment variables | + +## Quick Links + +- **Getting started (users)**: [docs.rustfs.com/installation](https://docs.rustfs.com/installation/) +- **Full docs**: [docs.rustfs.com](https://docs.rustfs.com) +- **Contributing**: [CONTRIBUTING.md](../CONTRIBUTING.md) and [doc/development.md](development.md) +- **CI and quality**: [.github/workflows/ci.yml](../.github/workflows/ci.yml), [Makefile](../Makefile) diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 0000000000..78928d3984 --- /dev/null +++ b/doc/architecture.md @@ -0,0 +1,35 @@ +# Architecture + +RustFS is a high-performance, distributed object storage system built in Rust with full S3 compatibility. This document summarizes the in-repository layout and main components. + +## Overview + +- **Core binary**: The `rustfs` crate is the main application (API, console, storage orchestration). +- **Workspace**: All shared logic lives in crates under `crates/`; see the root [Cargo.toml](../Cargo.toml) `[workspace].members` for the full list. + +## Main Components + +| Area | Crates | Purpose | +|------|--------|---------| +| **Core** | `rustfs` | Main server binary, S3 API, admin console, storage coordination | +| **Config** | `rustfs-config` | Configuration and environment variable handling | +| **Storage** | `rustfs-ecstore`, `rustfs-filemeta`, `rustfs-targets` | Erasure coding, metadata, target backends | +| **Auth & IAM** | `rustfs-appauth`, `rustfs-iam`, `rustfs-credentials`, `rustfs-keystone` | Authentication, policies, Keystone integration | +| **Security** | `rustfs-crypto`, `rustfs-kms` | Cryptography and key management | +| **Operations** | `rustfs-heal`, `rustfs-scanner`, `rustfs-audit` | Healing, scanning, audit targets | +| **Observability** | `rustfs-metrics`, `rustfs-obs`, `rustfs-notify` | Metrics, tracing, event notifications | +| **Protocols** | `rustfs-protocols`, `rustfs-s3select-api`, `rustfs-s3select-query` | FTPS/SFTP, S3 Select | +| **Utilities** | `rustfs-common`, `rustfs-utils`, `rustfs-rio`, `rustfs-workers` | Shared types, I/O, worker pools | + +The root [Cargo.toml](../Cargo.toml) is the source of truth for crate names and membership. + +## Scoped Guidance + +Path-specific rules for contributors and tooling are in `AGENTS.md` files: + +- [.github/AGENTS.md](../.github/AGENTS.md) +- [crates/AGENTS.md](../crates/AGENTS.md) +- [crates/config/AGENTS.md](../crates/config/AGENTS.md) +- Additional scoped files under `crates/`, `rustfs/src/admin/`, and `rustfs/src/storage/` + +See the root [AGENTS.md](../AGENTS.md) for precedence and mandatory pre-commit checks. diff --git a/doc/configuration.md b/doc/configuration.md new file mode 100644 index 0000000000..6da5507b01 --- /dev/null +++ b/doc/configuration.md @@ -0,0 +1,24 @@ +# Configuration Overview + +RustFS is configured via environment variables. This page gives an overview; the canonical source of truth is the `rustfs-config` crate. + +## Environment Variables + +- **Naming**: Use flat `RUSTFS_*` names (e.g. `RUSTFS_REGION`, `RUSTFS_ADDRESS`, `RUSTFS_VOLUMES`). Do not use module-segmented names like `RUSTFS_CONFIG_*`. +- **Constants and conventions**: See [crates/config/src/constants/](../crates/config/src/) and [crates/config/README.md](../crates/config/README.md) (including environment variable naming). + +## Key Variables (examples) + +| Variable | Purpose | +|----------|---------| +| `RUSTFS_REGION` | Deployment region | +| `RUSTFS_ADDRESS` | Server address | +| `RUSTFS_VOLUMES` | Storage volumes | +| `RUSTFS_SCANNER_ENABLED` | Enable scanner | +| `RUSTFS_HEAL_ENABLED` | Enable healing | + +Deprecated aliases are documented in [crates/config/README.md](../crates/config/README.md); compatibility behavior is maintained there. + +## Full Configuration Reference + +For all options, defaults, and deployment guides (including TLS and Keystone), use the official [RustFS Documentation](https://docs.rustfs.com). diff --git a/doc/development.md b/doc/development.md new file mode 100644 index 0000000000..f857e37550 --- /dev/null +++ b/doc/development.md @@ -0,0 +1,64 @@ +# Development Guide + +This page covers building, testing, and running quality checks for RustFS. For code formatting rules and PR expectations, see [CONTRIBUTING.md](../CONTRIBUTING.md). + +## Prerequisites + +- Rust (see root [Cargo.toml](../Cargo.toml) `rust-version`) +- For full quality gates: `make` (see [.config/make/](../.config/make/) and root [Makefile](../Makefile)) + +## Build + +```bash +# Build the RustFS binary +make build +# or +cargo build --release +``` + +## Testing + +```bash +# Run tests +make test +# or +cargo test --all-targets +``` + +## Code Quality (Mandatory Before Commit) + +Run all pre-commit checks: + +```bash +make pre-commit +``` + +If `make` is unavailable, run the equivalent steps from [.config/make/](../.config/make/). Typical steps: + +- Format: `cargo fmt --all` and `cargo fmt --all --check` +- Lint: `cargo clippy --all-targets --all-features -- -D warnings` +- Check: `cargo check --all-targets` +- Tests: `cargo test --all-targets` + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed formatting and clippy rules. + +## Make Targets + +- `make help` — Main help and categories +- `make help-build` — Build-related targets +- `make help-docker` — Docker and image targets +- `make fmt` / `make fmt-check` — Format and verify +- `make clippy` — Clippy +- `make check` — Compilation check +- `make test` — Tests +- `make pre-commit` — All checks required before commit + +## CI + +Quality gates are defined in [.github/workflows/ci.yml](../.github/workflows/ci.yml). Keep local checks aligned with CI so `make pre-commit` matches what runs on the branch. + +## Branch and PR Baseline + +- Use feature branches from latest `main`. +- Follow [Conventional Commits](https://www.conventionalcommits.org/), subject ≤ 72 characters. +- Use [.github/pull_request_template.md](../.github/pull_request_template.md) for PRs; use `N/A` for non-applicable sections.