130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
# Stick
|
|
|
|
Stick is a Rust web application starter template built on Axum, Askama, and MongoDB. Unlike traditional MVC architectures that organize code by technical layers (controllers, models, views), Stick is organized by **vertical slices** (features or use-cases). All files related to a specific domain feature—such as authentication or task management—live together in a single module.
|
|
|
|
This setup is ideal for medium-to-large projects where horizontal layers become hard to navigate, and compiling templates at runtime is too risky.
|
|
|
|
---
|
|
|
|
## Technical Architecture
|
|
|
|
### 1. Vertical Slice Layout
|
|
Each feature slice is self-contained. For example, the authentication domain has the following structure:
|
|
|
|
* `src/auth/models.rs`: BSON data structures and claims.
|
|
* `src/auth/repository.rs`: Database operations and query logic.
|
|
* `src/auth/handlers.rs`: Request/response lifecycle logic.
|
|
* `src/auth/extractors.rs`: Axum extractors for session state.
|
|
* `templates/auth/`: HTML markup templates rendered at compile-time.
|
|
|
|
### 2. Key Stack Decisions
|
|
* **Axum (v0.8)**: Handles routing, middleware, and request extraction.
|
|
* **Askama (v0.16)**: Evaluates and compiles HTML templates into Rust code at compile time. If you reference a variable or field that doesn't exist, the project fails to compile, catching UI rendering bugs before deployment.
|
|
* **MongoDB**: Standard Rust driver configured with BSON serialization.
|
|
* **Tailwind CSS**: Pre-compiled utility styling using a Node-based wrapper process.
|
|
* **Authentication**: Managed via JWT (JSON Web Tokens) stored in secure, encrypted `HttpOnly` cookies.
|
|
|
|
---
|
|
|
|
## Core Features Included
|
|
|
|
### Self-Provisioning Administrator
|
|
On startup, the application checks if the `users` collection in the MongoDB database is empty. If no users are found, it generates a secure, random 16-character alphanumeric password, hashes it with bcrypt, and creates a default `admin` account. The credentials are logged directly to standard output:
|
|
|
|
```text
|
|
======================================================
|
|
CREATED INITIAL ADMINISTRATOR ACCOUNT:
|
|
Username: admin
|
|
Password: [GeneratedPassword]
|
|
======================================================
|
|
```
|
|
|
|
### Decoupled Identity vs. Domain Entities
|
|
Stick strictly separates infrastructure/user models from business domain models:
|
|
* **Users** (`User`): Manage authentication, roles (`is_admin`), and settings under `/auth`.
|
|
* **Developers** (`Developer`): Plain domain entities managed under `/developers` that represent team members.
|
|
|
|
### User Management Panel (Administrators Only)
|
|
Accessible under `/auth/users` by logged-in administrators. The panel allows:
|
|
* Viewing all registered users and their administrative permissions.
|
|
* Editing user profiles, resetting passwords, and toggling administrator roles.
|
|
* Deleting users (with safeguards preventing administrators from deleting their own active accounts or revoking their own admin permissions).
|
|
* Registering new users.
|
|
|
|
### Self-Service Account Settings
|
|
Any authenticated user can change their own password by clicking their username in the navigation bar, which directs them to `/auth/password`.
|
|
|
|
---
|
|
|
|
## Setup and Running
|
|
|
|
### Prerequisites
|
|
* **Rust**: Toolchain v1.75+ (for native async traits).
|
|
* **Node.js & npm**: Required to build Tailwind CSS.
|
|
* **MongoDB**: Running locally on `mongodb://localhost:27017`.
|
|
|
|
### Local Setup
|
|
1. Copy the environment configuration:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
2. Build Tailwind CSS styling:
|
|
```bash
|
|
npm install
|
|
npx tailwindcss -i src/input.css -o static/tailwind.css
|
|
```
|
|
3. Run the development server:
|
|
```bash
|
|
cargo run
|
|
```
|
|
The server will start listening at `http://127.0.0.1:3000`.
|
|
|
|
### Running with Docker
|
|
A multi-stage `Dockerfile` is provided to compile Tailwind, compile the Rust binary, and bundle a lightweight Debian run container.
|
|
|
|
1. Build the image:
|
|
```bash
|
|
docker build -t stick .
|
|
```
|
|
2. Start the container (assumes MongoDB is running on the host machine):
|
|
```bash
|
|
docker run --name stick-app --rm --network="host" \
|
|
-e DATABASE_URL="mongodb://127.0.0.1:27017" \
|
|
-e DATABASE_NAME="stick_db" \
|
|
-e JWT_SECRET="super_secret_template_signing_key_that_is_at_least_32_characters_long" \
|
|
-e HOST="127.0.0.1" \
|
|
-e PORT="3009" \
|
|
stick
|
|
```
|
|
|
|
---
|
|
|
|
## Developer Guide: Adding a Feature Slice
|
|
|
|
To add a new feature (e.g. `projects`):
|
|
|
|
1. Create a module folder: `src/projects/`.
|
|
2. Define models in `models.rs` and database access functions in `repository.rs`.
|
|
3. Add request handlers in `handlers.rs`.
|
|
4. Create a router configuration in `src/projects/mod.rs` exposing a routing module setup:
|
|
```rust
|
|
pub fn router<S>() -> Router<S>
|
|
where
|
|
Config: axum::extract::FromRef<S>,
|
|
MongoUserRepository: axum::extract::FromRef<S>,
|
|
S: Clone + Send + Sync + 'static,
|
|
{
|
|
Router::new()
|
|
.route("/projects", get(handlers::get_projects))
|
|
}
|
|
```
|
|
5. Place HTML layouts under `templates/projects/` extending the `base.html` layout.
|
|
6. Register and merge the router in `src/main.rs`:
|
|
```rust
|
|
let app = Router::new()
|
|
.merge(main_view::router())
|
|
.merge(auth::router())
|
|
.merge(projects::router()) // Merged domain router
|
|
.with_state(state);
|
|
```
|