Heavily customized version of smokesignal - https://whtwnd.com/kayrozen.com/3lpwe4ymowg2t
kayrozen.com
1# Build
2
3This project uses the stable Rust toolchain (1.86 as of 5/31/25) and features a modern i18n system built on fluent-templates with unified template rendering.
4
5## Architecture Overview
6
7### I18n System (fluent-templates)
8smokesignal uses `fluent-templates` for high-performance internationalization:
9- **Static Loading**: Translations compiled into binary at build time
10- **Zero Runtime Overhead**: No file I/O for translation loading
11- **Automatic Fallbacks**: English fallback for missing translations
12- **Gender Support**: Full French Canadian gender variant support
13
14### Template Rendering System
15Unified template rendering with automatic context enrichment:
16- **Centralized API**: Single `TemplateRenderer` for all template operations
17- **Auto-Context**: Automatic i18n, HTMX, and gender context injection
18- **Error Handling**: Consistent error templates with context preservation
19- **Type Safety**: Compile-time template context validation
20
21## Bare Metal
22
23If you're not using devcontainers, you'll need to install Rust and the necessary dependencies on your system.
24
25### Prerequisites
26
27- Rust toolchain (1.86 or newer)
28- PostgreSQL
29- Redis or Valkey
30- SQLx CLI: `cargo install sqlx-cli@0.8.3 --no-default-features --features postgres`
31
32### Common Commands
33
34- **Build**: `cargo build`
35- **Check**: `cargo check`
36- **Lint**: `cargo clippy`
37- **Run tests**: `cargo test`
38- **Run server**: `cargo run --bin smokesignal`
39- **Run with debug**: `RUST_BACKTRACE=1 RUST_LOG=debug cargo run`
40- **Run database migrations**: `sqlx migrate run`
41
42### I18n-Specific Testing
43- **All i18n tests**: `cargo test i18n`
44- **Template tests**: `cargo test template`
45- **Template helpers**: `cargo test template_helpers`
46- **Middleware tests**: `cargo test middleware_i18n`
47- **Template renderer**: `cargo test template_renderer`
48
49### Build Options
50
51- **Build with embedded templates**: `cargo build --bin smokesignal --no-default-features -F embed`
52- **Build with template reloading**: `cargo build --bin smokesignal --no-default-features -F reload`
53
54#### Feature Flags
55- `embed`: Compile templates into binary (production, smaller runtime footprint)
56- `reload`: Enable template reloading (development, faster iteration)
57
58### Translation Validation
59
60The build process validates all translations at compile time:
61```bash
62# Validate all translations are accessible
63cargo test fluent_loader
64
65# Check translation completeness
66cargo test i18n -- --nocapture
67
68# Validate gender variants (French Canadian)
69cargo test gender
70```
71
72## Devcontainers (Recommended)
73
74The easiest way to get started is by using the provided devcontainer configuration with Visual Studio Code.
75
76### Setup
77
781. Install [Visual Studio Code](https://code.visualstudio.com/)
792. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
803. Clone this repository
814. Open the repository in VS Code
825. When prompted, click "Reopen in Container" or run the "Dev Containers: Reopen in Container" command
83
84The devcontainer will set up the following services:
85- Rust development environment with all dependencies
86- PostgreSQL database
87- Valkey (Redis-compatible) key-value store
88- Tailscale networking (optional)
89
90### Disabling Tailscale
91
92If you don't need the Tailscale service, you can disable it by:
93
941. Open `.devcontainer/docker-compose.yml`
952. Comment out or remove the `tailscale` service section
963. Rebuild the devcontainer (Command Palette > "Dev Containers: Rebuild Container")
97
98### VS Code Configuration
99
100The devcontainer comes with recommended VS Code extensions for Rust development:
101- Rust Analyzer
102- Jinja HTML
103- Even Better TOML
104
105A launch configuration example is provided in `.vscode/launch.example.json`. Copy this to `.vscode/launch.json` to enable debugging in VS Code.
106
107## Development Configuration
108
109The application requires several environment variables for cryptographic operations. You can generate appropriate values using the included `crypto` binary.
110
111### Generating Cryptographic Keys
112
113Generate a random 64-byte key encoded in base64:
114
115```
116cargo run --bin crypto -- key
117```
118
119Generate a JWK (JSON Web Key):
120
121```
122cargo run --bin crypto -- jwk
123```
124
125The generated JWK should be added to a JWKS (JSON Web Key Set) in the file `keys.json`:
126
127```json
128{
129 "keys": [
130 { "kid": "01J7PM272ZF0DYZAPR3499VBTM" ...},
131 { "kid": "01J8G3J3CDVJ15C63PMCDS3K97" ...},
132 { "kid": "01JF2QS2S86SG2R23HTZ0JKB76" ...}
133 ]
134 }
135 ```
136
137### Environment Variables
138
139Set the following environment variables with values generated from the commands above:
140
141- `SIGNING_KEYS`: The path to the `keys.json` file
142- `OAUTH_ACTIVE_KEYS`: A comma seperated list of JWK IDs used to actively sign OAuth sessions
143- `DESTINATION_KEY`: A JWK ID used to sign destination (used in redirects) values
144- `HTTP_COOKIE_KEY`: A key used to encrypt HTTP sessions
145
146You can add these to your .env file or set them directly in your environment.
147
148### Additional Configuration for Airgapped Development
149
150For airgapped development, you can configure:
151
152- `PLC_HOSTNAME`: Custom PLC hostname for development
153- `DNS_NAMESERVERS`: Custom DNS nameservers
154- `ADMIN_DIDS`: Comma-separated list of admin DIDs
155
156Example:
157```
158PLC_HOSTNAME=localhost:3000
159DNS_NAMESERVERS=1.1.1.1,1.0.0.1
160ADMIN_DIDS=did:plc:yourdevdid1,did:plc:yourdevdid2
161```