Skip to content

Commit fd68928

Browse files
dannywillemsdannywillems
committed
Website: add getting-started section for devs
1 parent 72651fa commit fd68928

16 files changed

+482
-0
lines changed

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Test Documentation Scripts
2+
3+
on:
4+
push:
5+
branches: [develop, main]
6+
paths:
7+
- 'website/scripts/**'
8+
- 'website/docs/developers/getting-started.md'
9+
- '.github/workflows/test-docs-scripts.yml'
10+
pull_request:
11+
branches: [develop, main]
12+
paths:
13+
- 'website/scripts/**'
14+
- 'website/docs/developers/getting-started.md'
15+
- '.github/workflows/test-docs-scripts.yml'
16+
schedule:
17+
# Run weekly to catch environment drift
18+
- cron: '0 2 * * 1'
19+
workflow_dispatch:
20+
21+
jobs:
22+
test-system-setup:
23+
name: Test System Setup Scripts
24+
runs-on: ubuntu-22.04
25+
26+
steps:
27+
- name: Checkout repository
28+
uses: actions/checkout@v4
29+
30+
- name: Test system dependencies installation
31+
run: |
32+
./website/scripts/setup/install-system-deps.sh
33+
34+
- name: Test Node.js installation
35+
run: |
36+
./website/scripts/setup/install-nodejs.sh
37+
38+
- name: Test Rust installation
39+
run: |
40+
./website/scripts/setup/install-rust.sh
41+
42+
- name: Test WASM tools installation
43+
run: |
44+
# Source cargo environment first
45+
source ~/.cargo/env
46+
./website/scripts/setup/install-wasm-tools.sh
47+
48+
- name: Verify installations
49+
run: |
50+
echo "Verifying installed tools..."
51+
source ~/.cargo/env
52+
rustc --version
53+
cargo --version
54+
node --version
55+
npm --version
56+
protoc --version
57+
sqlite3 --version
58+
wasm-pack --version
59+
60+
test-docker-setup:
61+
name: Test Docker Setup Script
62+
runs-on: ubuntu-22.04
63+
64+
steps:
65+
- name: Checkout repository
66+
uses: actions/checkout@v4
67+
68+
- name: Test Docker installation
69+
run: |
70+
./website/scripts/setup/install-docker.sh
71+
72+
- name: Verify Docker installation
73+
run: |
74+
sudo docker --version
75+
sudo docker run hello-world

‎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: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
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 targets:
85+
86+
```bash
87+
make help
88+
```
89+
90+
Common development targets include:
91+
92+
```bash
93+
# Basic builds
94+
make build # Debug build for development
95+
make build-release # Optimized build for production
96+
make check # Check code without building
97+
98+
# Testing
99+
make test # Run test suite
100+
make test-release # Run tests in release mode
101+
102+
# Code quality
103+
make format # Format all code
104+
make lint # Run static analysis
105+
make clean # Clean build artifacts
106+
```
107+
108+
### Environment Configuration
109+
110+
Some components require environment variables:
111+
112+
```bash
113+
# For SQLx database operations (heartbeats processor)
114+
export DATABASE_URL="sqlite:///tmp/heartbeats.db"
115+
116+
# For archive node development
117+
export OPENMINA_ARCHIVE_ADDRESS="http://localhost:3007"
118+
export PG_USER="openmina"
119+
export PG_PW="openminaopenmina"
120+
export PG_DB="openmina_archive"
121+
```
122+
123+
## Architecture Overview
124+
125+
For detailed information about OpenMina's architecture, Redux-style state machine pattern, and component organization, please see the [Architecture Documentation](./architecture.md).
126+
127+
## Running OpenMina
128+
129+
### Basic Node
130+
131+
```bash
132+
# Run a basic node (after building)
133+
./target/release/openmina node --network devnet
134+
```
135+
136+
### Archive Node
137+
138+
```bash
139+
# Set up PostgreSQL database
140+
make postgres-setup
141+
142+
# Run archive node
143+
make run-archive
144+
```
145+
146+
### Development Server
147+
148+
For web development with the frontend:
149+
150+
```bash
151+
# Build and serve documentation
152+
make docs-serve
153+
154+
# The documentation will be available at http://localhost:3000
155+
```
156+
157+
## Debugging and Development Tools
158+
159+
### Logging
160+
161+
OpenMina uses structured logging with different levels:
162+
163+
```bash
164+
# Set log level
165+
export RUST_LOG=debug
166+
167+
# Run with verbose logging
168+
RUST_LOG=trace ./target/release/openmina node --network devnet
169+
```
170+
171+
### Frontend Development
172+
173+
The project includes a web-based dashboard:
174+
175+
```bash
176+
# Build and run frontend (see frontend/README.md for details)
177+
cd frontend
178+
npm install
179+
npm start
180+
```
181+
182+
### Testing Framework
183+
184+
OpenMina includes a comprehensive testing framework:
185+
186+
```bash
187+
# Build testing binary
188+
make build-testing
189+
190+
# Run specific test scenarios
191+
./target/release/openmina-node-testing --help
192+
```
193+
194+
## Next Steps
195+
196+
1. **Explore the Codebase**: Start with
197+
[Architecture Documentation](./architecture.md)
198+
2. **Run Tests**: Ensure your setup works by running `make test`
199+
3. **Join the Community**: Connect with other developers on
200+
[Discord](https://discord.com/channels/484437221055922177/1290662938734231552)
201+
4. **Read CLAUDE.md**: Check the project-specific development guide in the root
202+
directory
203+
204+
## Getting Help
205+
206+
- **Documentation**:
207+
[https://o1-labs.github.io/openmina/](https://o1-labs.github.io/openmina/)
208+
- **Discord**:
209+
[OpenMina Community](https://discord.com/channels/484437221055922177/1290662938734231552)
210+
- **Issues**: [GitHub Issues](https://github.com/o1-labs/openmina/issues)
211+
- **API Docs**:
212+
[Rust Documentation](https://o1-labs.github.io/openmina/api-docs/)
213+
214+
Welcome to the OpenMina development community! 🎉

‎website/package-lock.json‎

Lines changed: 75 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎website/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"@docusaurus/module-type-aliases": "^3.8.1",
2828
"@docusaurus/tsconfig": "^3.8.1",
2929
"@docusaurus/types": "^3.8.1",
30+
"raw-loader": "^4.0.2",
3031
"typescript": "~5.6.2"
3132
},
3233
"browserslist": {

0 commit comments

Comments
 (0)