Skip to content

Commit ea569e8

Browse files
dannywillemsdannywillems
committed
Website: add getting-started section for devs
1 parent bc31be0 commit ea569e8

16 files changed

+491
-0
lines changed

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

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
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 (${{ matrix.os }})
24+
runs-on: ${{ matrix.os }}
25+
strategy:
26+
matrix:
27+
os: [ubuntu-22.04, ubuntu-24.04]
28+
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
33+
- name: Test system dependencies installation
34+
run: |
35+
./website/scripts/setup/install-system-deps.sh
36+
37+
- name: Test Node.js installation
38+
run: |
39+
./website/scripts/setup/install-nodejs.sh
40+
41+
- name: Test Rust installation
42+
run: |
43+
./website/scripts/setup/install-rust.sh
44+
45+
- name: Test WASM tools installation
46+
run: |
47+
# Source cargo environment first
48+
source ~/.cargo/env
49+
./website/scripts/setup/install-wasm-tools.sh
50+
51+
- name: Verify installations
52+
run: |
53+
echo "Verifying installed tools..."
54+
source ~/.cargo/env
55+
rustc --version
56+
cargo --version
57+
node --version
58+
npm --version
59+
protoc --version
60+
sqlite3 --version
61+
wasm-pack --version
62+
63+
test-docker-setup:
64+
name: Test Docker Setup Script (${{ matrix.os }})
65+
runs-on: ${{ matrix.os }}
66+
strategy:
67+
matrix:
68+
os: [ubuntu-22.04, ubuntu-24.04]
69+
70+
steps:
71+
- name: Checkout repository
72+
uses: actions/checkout@v4
73+
74+
- name: Test Docker installation
75+
run: |
76+
./website/scripts/setup/install-docker.sh
77+
78+
- name: Verify Docker installation
79+
run: |
80+
sudo docker --version
81+
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: 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/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.

0 commit comments

Comments
 (0)