Skip to content

Commit c1c43cc

Browse files
dannywillemsdannywillems
committed
Website: add getting-started section for devs
1 parent 875fe55 commit c1c43cc

16 files changed

+503
-0
lines changed

‎.github/workflows/test-docs-scripts.yml

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
name: Test Documentation Scripts
2+
3+
# This workflow tests the documentation setup scripts to ensure they work correctly.
4+
# It runs nightly and on-demand to avoid slowing down regular development workflow,
5+
# since documentation builds can take a long time to complete.
6+
on:
7+
pull_request:
8+
types: [labeled]
9+
# Only runs when 'test-doc-scripts' label is added to a PR
10+
schedule:
11+
# Run nightly to catch environment drift and ensure scripts stay functional
12+
- cron: '0 2 * * *'
13+
workflow_dispatch:
14+
# Allow manual triggering for testing
15+
16+
jobs:
17+
test-system-setup:
18+
name: Test System Setup Scripts (${{ matrix.os }})
19+
runs-on: ${{ matrix.os }}
20+
# Only run if the event is scheduled, manual, or PR has test-doc-scripts label
21+
# This prevents long-running tests from blocking regular development workflow
22+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts')
23+
strategy:
24+
matrix:
25+
os: [ubuntu-22.04, ubuntu-24.04]
26+
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
31+
- name: Test system dependencies installation
32+
run: |
33+
./website/docs/developers/scripts/setup/install-system-deps.sh
34+
35+
- name: Test Node.js installation
36+
run: |
37+
./website/docs/developers/scripts/setup/install-nodejs.sh
38+
39+
- name: Test Rust installation
40+
run: |
41+
./website/docs/developers/scripts/setup/install-rust.sh
42+
43+
- name: Test WASM tools installation
44+
run: |
45+
# Source cargo environment first
46+
source ~/.cargo/env
47+
./website/docs/developers/scripts/setup/install-wasm-tools.sh
48+
49+
- name: Test specialised builds
50+
run: |
51+
# Source cargo environment first
52+
source ~/.cargo/env
53+
./website/docs/developers/scripts/setup/build-specialized.sh
54+
55+
- name: Test format and lint
56+
run: |
57+
# Source cargo environment first
58+
source ~/.cargo/env
59+
./website/docs/developers/scripts/setup/format-and-lint.sh
60+
61+
- name: Test run tests
62+
run: |
63+
# Source cargo environment first
64+
source ~/.cargo/env
65+
./website/docs/developers/scripts/setup/run-tests.sh
66+
67+
- name: Verify installations
68+
run: |
69+
echo "Verifying installed tools..."
70+
source ~/.cargo/env
71+
rustc --version
72+
cargo --version
73+
node --version
74+
npm --version
75+
protoc --version
76+
sqlite3 --version
77+
wasm-pack --version
78+
79+
test-docker-setup:
80+
name: Test Docker Setup Script (${{ matrix.os }})
81+
runs-on: ${{ matrix.os }}
82+
# Only run if the event is scheduled, manual, or PR has test-doc-scripts label
83+
# This prevents long-running tests from blocking regular development workflow
84+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || contains(github.event.pull_request.labels.*.name, 'test-doc-scripts')
85+
strategy:
86+
matrix:
87+
os: [ubuntu-22.04, ubuntu-24.04]
88+
89+
steps:
90+
- name: Checkout repository
91+
uses: actions/checkout@v4
92+
93+
- name: Test Docker installation
94+
run: |
95+
./website/docs/developers/scripts/setup/install-docker.sh
96+
97+
- name: Verify Docker installation
98+
run: |
99+
sudo docker --version
100+
sudo docker run hello-world

‎Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,7 @@ postgres-setup: ## Set up PostgreSQL database for archive node
303303
@sudo -u postgres createdb -O $(PG_USER) $(PG_USER) 2>/dev/null || true
304304

305305
# Documentation targets
306+
306307
.PHONY: docs-install
307308
docs-install: ## Install documentation dependencies
308309
@echo "Installing documentation dependencies..."

‎rust-toolchain.toml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
11
[toolchain]
22
channel = "1.84"
3+
4+
# NOTE: When updating the Rust version here, also update:
5+
# - website/scripts/setup/install-rust.sh
6+
# - website/docs/developers/getting-started.mdx (references the install-rust.sh script)

‎website/docs/developers/getting-started.mdx

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
# Getting Started for Developers
6+
7+
import CodeBlock from "@theme/CodeBlock";
8+
import InstallRustSh from "!!raw-loader!./scripts/setup/install-rust.sh";
9+
import InstallSystemDepsSh from "!!raw-loader!./scripts/setup/install-system-deps.sh";
10+
import InstallNodejsSh from "!!raw-loader!./scripts/setup/install-nodejs.sh";
11+
import InstallDockerSh from "!!raw-loader!./scripts/setup/install-docker.sh";
12+
import InstallWasmToolsSh from "!!raw-loader!./scripts/setup/install-wasm-tools.sh";
13+
import CloneAndBuildSh from "!!raw-loader!./scripts/setup/clone-and-build.sh";
14+
import BuildSpecializedSh from "!!raw-loader!./scripts/setup/build-specialized.sh";
15+
import RunTestsSh from "!!raw-loader!./scripts/setup/run-tests.sh";
16+
import FormatAndLintSh from "!!raw-loader!./scripts/setup/format-and-lint.sh";
17+
18+
Welcome to OpenMina development! This guide will help you set up your
19+
development environment and build OpenMina from source.
20+
21+
## Prerequisites
22+
23+
### System Requirements
24+
25+
- **Operating System**: Ubuntu 20.04+ or Debian 11+ (other Linux distributions
26+
may work but are not officially supported)
27+
- **Memory**: At least 8GB RAM (16GB recommended)
28+
- **Storage**: At least 20GB free space
29+
- **Network**: Stable internet connection for downloading dependencies
30+
31+
### Required Tools
32+
33+
#### 1. Rust Toolchain
34+
35+
OpenMina requires both stable and nightly Rust toolchains:
36+
37+
<CodeBlock language="bash">{InstallRustSh}</CodeBlock>
38+
39+
#### 2. System Dependencies
40+
41+
<CodeBlock language="bash">{InstallSystemDepsSh}</CodeBlock>
42+
43+
#### 3. Additional Development Tools
44+
45+
**Node.js (for documentation and frontend):**
46+
47+
<CodeBlock language="bash">{InstallNodejsSh}</CodeBlock>
48+
49+
**Docker (optional, for containerized builds):**
50+
51+
<CodeBlock language="bash">{InstallDockerSh}</CodeBlock>
52+
53+
#### 4. WASM Tools (for web node development)
54+
55+
<CodeBlock language="bash">{InstallWasmToolsSh}</CodeBlock>
56+
57+
## Clone and Build OpenMina
58+
59+
### 1. Clone the Repository and Build
60+
61+
<CodeBlock language="bash">{CloneAndBuildSh}</CodeBlock>
62+
63+
### 2. Specialized Builds
64+
65+
For more advanced builds including release mode, WebAssembly, and specialized
66+
components:
67+
68+
<CodeBlock language="bash">{BuildSpecializedSh}</CodeBlock>
69+
70+
### 3. Run Tests
71+
72+
<CodeBlock language="bash">{RunTestsSh}</CodeBlock>
73+
74+
## Development Workflow
75+
76+
### Code Quality and Formatting
77+
78+
OpenMina maintains strict code quality standards:
79+
80+
<CodeBlock language="bash">{FormatAndLintSh}</CodeBlock>
81+
82+
### Working with Makefiles
83+
84+
The project's Makefile provides many helpful commands. View all available
85+
targets:
86+
87+
```bash
88+
make help
89+
```
90+
91+
Common development targets include:
92+
93+
```bash
94+
# Basic builds
95+
make build # Debug build for development
96+
make build-release # Optimized build for production
97+
make check # Check code without building
98+
99+
# Testing
100+
make test # Run test suite
101+
make test-release # Run tests in release mode
102+
103+
# Code quality
104+
make format # Format all code
105+
make lint # Run static analysis
106+
make clean # Clean build artifacts
107+
```
108+
109+
### Environment Configuration
110+
111+
Some components require environment variables:
112+
113+
```bash
114+
# For SQLx database operations (heartbeats processor)
115+
export DATABASE_URL="sqlite:///tmp/heartbeats.db"
116+
117+
# For archive node development
118+
export OPENMINA_ARCHIVE_ADDRESS="http://localhost:3007"
119+
export PG_USER="openmina"
120+
export PG_PW="openminaopenmina"
121+
export PG_DB="openmina_archive"
122+
```
123+
124+
## Architecture Overview
125+
126+
For detailed information about OpenMina's architecture, Redux-style state
127+
machine pattern, and component organization, please see the
128+
[Architecture Documentation](./architecture.md).
129+
130+
## Running OpenMina
131+
132+
### Basic Node
133+
134+
```bash
135+
# Run a basic node (after building)
136+
./target/release/openmina node --network devnet
137+
```
138+
139+
### Archive Node
140+
141+
```bash
142+
# Set up PostgreSQL database
143+
make postgres-setup
144+
145+
# Run archive node
146+
make run-archive
147+
```
148+
149+
### Development Server
150+
151+
For web development with the frontend:
152+
153+
```bash
154+
# Build and serve documentation
155+
make docs-serve
156+
157+
# The documentation will be available at http://localhost:3000
158+
```
159+
160+
## Debugging and Development Tools
161+
162+
### Logging
163+
164+
OpenMina uses structured logging with different levels:
165+
166+
```bash
167+
# Set log level
168+
export RUST_LOG=debug
169+
170+
# Run with verbose logging
171+
RUST_LOG=trace ./target/release/openmina node --network devnet
172+
```
173+
174+
### Frontend Development
175+
176+
The project includes a web-based dashboard:
177+
178+
```bash
179+
# Build and run frontend (see frontend/README.md for details)
180+
cd frontend
181+
npm install
182+
npm start
183+
```
184+
185+
### Testing Framework
186+
187+
OpenMina includes a comprehensive testing framework:
188+
189+
```bash
190+
# Build testing binary
191+
make build-testing
192+
193+
# Run specific test scenarios
194+
./target/release/openmina-node-testing --help
195+
```
196+
197+
## Next Steps
198+
199+
1. **Explore the Codebase**: Start with
200+
[Architecture Documentation](./architecture.md)
201+
2. **Run Tests**: Ensure your setup works by running `make test`
202+
3. **Join the Community**: Connect with other developers on
203+
[Discord](https://discord.com/channels/484437221055922177/1290662938734231552)
204+
4. **Read CLAUDE.md**: Check the project-specific development guide in the root
205+
directory
206+
207+
## Getting Help
208+
209+
- **Documentation**:
210+
[https://o1-labs.github.io/openmina/](https://o1-labs.github.io/openmina/)
211+
- **Discord**:
212+
[OpenMina Community](https://discord.com/channels/484437221055922177/1290662938734231552)
213+
- **Issues**: [GitHub Issues](https://github.com/o1-labs/openmina/issues)
214+
- **API Docs**:
215+
[Rust Documentation](https://o1-labs.github.io/openmina/api-docs/)
216+
217+
Welcome to the OpenMina development community! 🎉

‎website/docs/developers/scripts/setup/build-specialized.sh

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Build in release mode (slower compilation, faster runtime)
2+
echo "Building in release mode..."
3+
make build-release
4+
5+
# Build ledger components (requires nightly Rust)
6+
echo "Building ledger components..."
7+
make build-ledger
8+
9+
# Build WebAssembly node for browser
10+
echo "Building WebAssembly node..."
11+
make build-wasm
12+
13+
# Build testing framework with scenario generators
14+
echo "Building testing framework..."
15+
make build-testing
16+
17+
# Build VRF (Verifiable Random Function) components
18+
echo "Building VRF components..."
19+
make build-vrf

‎website/docs/developers/scripts/setup/clone-and-build.sh

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
git clone https://github.com/o1-labs/openmina.git
2+
cd openmina
3+
4+
# Download required circuits
5+
echo "Downloading required circuits..."
6+
make download-circuits
7+
8+
# Build in debug mode (faster compilation, slower runtime)
9+
echo "Building OpenMina in debug mode..."
10+
make build

‎website/docs/developers/scripts/setup/format-and-lint.sh

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Format code (required before commits)
2+
echo "Formatting code..."
3+
make format
4+
5+
# Check formatting
6+
echo "Checking code formatting..."
7+
make check-format
8+
9+
# Run linter (clippy)
10+
echo "Running linter..."
11+
make lint
12+
13+
# Fix trailing whitespaces (mandatory before commits)
14+
echo "Fixing trailing whitespaces..."
15+
make fix-trailing-whitespace
16+
17+
# Check for trailing whitespaces
18+
echo "Checking for trailing whitespaces..."
19+
make check-trailing-whitespace

‎website/docs/developers/scripts/setup/install-docker.sh

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Install Docker
2+
curl -fsSL https://get.docker.com -o get-docker.sh
3+
sudo sh get-docker.sh
4+
sudo usermod -aG docker $USER
5+
6+
# Clean up
7+
rm get-docker.sh

‎website/docs/developers/scripts/setup/install-nodejs.sh

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Install Node.js (version 18+ recommended)
2+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
3+
sudo apt-get install -y nodejs

0 commit comments

Comments
 (0)