Skip to content

Commit 3a7ce34

Browse files
dannywillemsdannywillems
committed
Website/frontend: add page
1 parent af8ea2e commit 3a7ce34

File tree

11 files changed

+396
-0
lines changed

11 files changed

+396
-0
lines changed

‎website/docs/developers/frontend.mdx‎

Lines changed: 335 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,335 @@
1+
---
2+
title: Frontend Dashboard
3+
description: How to run and develop the Mina Rust frontend dashboard
4+
sidebar_position: 8
5+
---
6+
7+
import CodeBlock from "@theme/CodeBlock";
8+
import InstallNvm from "!!raw-loader!./scripts/frontend/install-nvm.sh";
9+
import InstallNodejs from "!!raw-loader!./scripts/frontend/install-nodejs.sh";
10+
import InstallAngularCli from "!!raw-loader!./scripts/frontend/install-angular-cli.sh";
11+
import InstallDependencies from "!!raw-loader!./scripts/frontend/install-dependencies.sh";
12+
import StartDevelopment from "!!raw-loader!./scripts/frontend/start-development.sh";
13+
import BuildProduction from "!!raw-loader!./scripts/frontend/build-production.sh";
14+
import DockerRun from "!!raw-loader!./scripts/frontend/docker-run.sh";
15+
import DockerBuild from "!!raw-loader!./scripts/frontend/docker-build.sh";
16+
import DockerComposeRun from "!!raw-loader!./scripts/frontend/docker-compose-run.sh";
17+
import BuildO1jsWrapper from "!!raw-loader!./scripts/frontend/build-o1js-wrapper.sh";
18+
19+
# Frontend Dashboard
20+
21+
The Mina Rust frontend is an Angular-based web dashboard that provides real-time
22+
monitoring and debugging capabilities for your Mina Rust node. It offers
23+
insights into node state, peer connections, block production, and more.
24+
25+
## Quick start
26+
27+
### Using Docker (recommended)
28+
29+
The easiest way to run the frontend is using Docker:
30+
31+
<CodeBlock language="bash" title="Run frontend with Docker">
32+
{DockerRun}
33+
</CodeBlock>
34+
35+
To connect the frontend to your node, use Docker Compose:
36+
37+
<CodeBlock language="bash" title="Run with Docker Compose">
38+
{DockerComposeRun}
39+
</CodeBlock>
40+
41+
### Running locally
42+
43+
#### Prerequisites
44+
45+
First, install Node Version Manager (nvm):
46+
47+
<CodeBlock language="bash" title="Install nvm">
48+
{InstallNvm}
49+
</CodeBlock>
50+
51+
Then install Node.js v23:
52+
53+
<CodeBlock language="bash" title="Install Node.js">
54+
{InstallNodejs}
55+
</CodeBlock>
56+
57+
Install Angular CLI:
58+
59+
<CodeBlock language="bash" title="Install Angular CLI">
60+
{InstallAngularCli}
61+
</CodeBlock>
62+
63+
#### Installation and setup
64+
65+
Clone the repository and install dependencies:
66+
67+
<CodeBlock language="bash" title="Install frontend dependencies">
68+
{InstallDependencies}
69+
</CodeBlock>
70+
71+
Start the development server:
72+
73+
<CodeBlock language="bash" title="Start development server">
74+
{StartDevelopment}
75+
</CodeBlock>
76+
77+
## Development
78+
79+
### Project structure
80+
81+
```
82+
frontend/
83+
├── src/
84+
│ ├── app/ # Angular application components
85+
│ ├── assets/ # Static assets and o1js wrapper
86+
│ └── environments/ # Environment configurations
87+
├── docker/ # Docker-related files
88+
├── angular.json # Angular configuration
89+
└── package.json # Dependencies and scripts
90+
```
91+
92+
### Available scripts
93+
94+
```bash
95+
# Development server with hot reload
96+
npm start
97+
98+
# Production build
99+
npm run build
100+
101+
# Run tests
102+
npm test
103+
104+
# Run linting
105+
npm run lint
106+
107+
# Build for specific environment
108+
npm run build -- --configuration=production
109+
npm run build -- --configuration=local
110+
npm run build -- --configuration=webnodelocal
111+
```
112+
113+
### Environment configurations
114+
115+
The frontend supports multiple environment configurations:
116+
117+
- **development**:
118+
[Default development configuration](https://github.com/o1-labs/mina-rust/blob/develop/frontend/src/environments/environment.ts)
119+
- **production**:
120+
[Optimized production build](https://github.com/o1-labs/mina-rust/blob/develop/frontend/src/environments/environment.prod.ts)
121+
- **local**:
122+
[For connecting to local node](https://github.com/o1-labs/mina-rust/blob/develop/frontend/src/environments/environment.local.ts)
123+
- **producer**:
124+
[For block producer nodes](https://github.com/o1-labs/mina-rust/blob/develop/frontend/src/environments/environment.producer.ts)
125+
- **webnodelocal**:
126+
[For WebNode development](https://github.com/o1-labs/mina-rust/blob/develop/frontend/src/environments/environment.webnodelocal.ts)
127+
- **fuzzing**:
128+
[For fuzzing tests](https://github.com/o1-labs/mina-rust/blob/develop/frontend/src/environments/environment.fuzzing.ts)
129+
130+
Configure by editing files in
131+
[`src/environments/`](https://github.com/o1-labs/mina-rust/tree/develop/frontend/src/environments).
132+
133+
### Using the o1js wrapper
134+
135+
The frontend includes an o1js wrapper for zkApp interactions:
136+
137+
<CodeBlock language="bash" title="Build o1js wrapper">
138+
{BuildO1jsWrapper}
139+
</CodeBlock>
140+
141+
The wrapper is accessible via `BenchmarksWalletsZkService => o1jsInterface` in
142+
the Angular application.
143+
144+
## Docker deployment
145+
146+
### Building the Docker image
147+
148+
Build the frontend Docker image locally:
149+
150+
<CodeBlock language="bash" title="Build Docker image">
151+
{DockerBuild}
152+
</CodeBlock>
153+
154+
You can also build with a specific configuration:
155+
156+
```bash
157+
# Build with development configuration
158+
docker build --build-arg BUILD_CONFIGURATION=development -t mina-frontend .
159+
160+
# Build with webnode configuration
161+
docker build --build-arg BUILD_CONFIGURATION=webnodelocal -t mina-frontend .
162+
```
163+
164+
### Production build
165+
166+
For production deployment, build the optimized version:
167+
168+
<CodeBlock language="bash" title="Build for production">
169+
{BuildProduction}
170+
</CodeBlock>
171+
172+
### Docker Compose setup
173+
174+
The project includes a Docker Compose configuration for running the frontend
175+
with a node:
176+
177+
```yaml
178+
services:
179+
mina-node:
180+
image: o1labs/mina-rust:latest
181+
ports:
182+
- "8302:8302"
183+
volumes:
184+
- ./mina-workdir:/root/.mina:rw
185+
186+
frontend:
187+
image: o1labs/mina-rust-frontend:latest
188+
ports:
189+
- "8070:80"
190+
environment:
191+
MINA_FRONTEND_ENVIRONMENT: compose
192+
```
193+
194+
### Environment variables
195+
196+
The frontend Docker container supports these environment variables:
197+
198+
- `MINA_FRONTEND_ENVIRONMENT`: Sets the environment configuration (`compose`,
199+
`webnode`, etc.)
200+
- `MINA_SIGNALING_URL`: WebRTC signaling server URL (for WebNode)
201+
- `MINA_WASM_VERSION`: Version of WASM files to download (for WebNode)
202+
203+
Example with custom environment variables:
204+
205+
```bash
206+
docker run -d \
207+
--name mina-frontend \
208+
-p 8070:80 \
209+
-e MINA_FRONTEND_ENVIRONMENT=webnode \
210+
-e MINA_SIGNALING_URL=wss://signal.example.com \
211+
o1labs/mina-rust-frontend:latest
212+
```
213+
214+
## Features
215+
216+
### Main dashboard views
217+
218+
- **Overview**: Node status, sync state, and key metrics
219+
- **State**: Detailed state machine visualization
220+
- **Peers**: Active peer connections and network topology
221+
- **Blocks**: Block production and validation metrics
222+
- **Transactions**: Transaction pool monitoring
223+
- **SNARKs**: SNARK work and verification status
224+
- **Logs**: Real-time node logs and debugging
225+
226+
### WebNode support
227+
228+
The frontend includes WebNode support for running a Mina node directly in the
229+
browser:
230+
231+
1. Circuit file downloads are handled automatically
232+
2. WASM binaries are cached for performance
233+
3. WebRTC signaling enables peer-to-peer connections
234+
235+
To enable WebNode features, use the `webnode` environment configuration.
236+
237+
## Troubleshooting
238+
239+
### Common issues
240+
241+
#### Port conflicts
242+
243+
If port 8070 is already in use:
244+
245+
```bash
246+
# Check what's using port 8070
247+
lsof -i :8070
248+
249+
# Use a different port
250+
docker run -d -p 8080:80 mina-frontend
251+
```
252+
253+
#### Connection issues
254+
255+
Ensure the node is running and accessible:
256+
257+
```bash
258+
# Check node status
259+
curl http://localhost:8302/node/status
260+
261+
# Check Docker network connectivity
262+
docker network ls
263+
docker network inspect bridge
264+
```
265+
266+
#### Build failures
267+
268+
If the build fails, try these steps:
269+
270+
```bash
271+
# Clear npm cache
272+
npm cache clean --force
273+
274+
# Remove node_modules and reinstall
275+
rm -rf node_modules package-lock.json
276+
npm install
277+
278+
# Update Angular CLI
279+
npm update @angular/cli
280+
281+
# For Docker builds, rebuild without cache
282+
docker build --no-cache -t mina-frontend .
283+
```
284+
285+
### Development tips
286+
287+
1. **Hot reload**: The development server at `http://localhost:4200` supports
288+
hot module replacement
289+
2. **Chrome DevTools**: Install the Angular DevTools extension for component
290+
debugging
291+
3. **Network tab**: Monitor WebSocket connections to the node in browser
292+
DevTools
293+
4. **Console logging**: Check browser console for detailed error messages
294+
5. **Source maps**: Development builds include source maps for easier debugging
295+
296+
## API integration
297+
298+
The frontend connects to the Mina Rust node through several APIs:
299+
300+
- **REST API**: Node status and configuration at port 8302
301+
- **WebSocket**: Real-time state updates and logs
302+
- **GraphQL**: Query interface for blockchain data (when enabled)
303+
304+
Default endpoints:
305+
306+
- Local development: `http://localhost:8302`
307+
- Docker Compose: `http://mina-node:8302`
308+
- Production: Configure in environment files
309+
310+
## Contributing
311+
312+
When contributing to the frontend:
313+
314+
1. Follow Angular style guide and best practices
315+
2. Write unit tests for new components and services
316+
3. Update this documentation for new features
317+
4. Test with both local and Docker deployments
318+
5. Ensure compatibility with latest node API changes
319+
6. Run linting before submitting PRs: `npm run lint`
320+
321+
### Code style
322+
323+
The project uses:
324+
325+
- TypeScript for type safety
326+
- Angular CLI for consistent project structure
327+
- ESLint for code quality
328+
- Prettier for code formatting
329+
330+
## Additional resources
331+
332+
- [Angular Documentation](https://angular.io/docs)
333+
- [Docker Documentation](https://docs.docker.com/)
334+
- [Mina Protocol Documentation](https://docs.minaprotocol.com/)
335+
- [Frontend README](https://github.com/o1-labs/mina-rust/tree/main/frontend)

‎website/docs/developers/scripts/frontend/build-o1js-wrapper.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Navigate to o1js wrapper directory
2+
cd src/assets/o1js
3+
4+
# Install wrapper dependencies
5+
npm install
6+
7+
# Build the o1js wrapper
8+
npm run build-o1jswrapper

‎website/docs/developers/scripts/frontend/build-production.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Build for production
2+
npm run build -- --configuration=production
3+
4+
# The build output will be in dist/frontend/

‎website/docs/developers/scripts/frontend/docker-build.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Build the frontend Docker image locally
2+
cd frontend
3+
4+
# Build with default production configuration
5+
docker build -t mina-frontend .
6+
7+
# Run the locally built container
8+
docker run -d -p 8070:80 mina-frontend

‎website/docs/developers/scripts/frontend/docker-compose-run.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Run both node and frontend using Docker Compose
2+
docker compose up -d
3+
4+
# View logs
5+
docker compose logs -f frontend
6+
7+
# Stop services
8+
docker compose down

‎website/docs/developers/scripts/frontend/docker-run.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Pull and run the frontend Docker image
2+
docker pull o1labs/mina-rust-frontend:latest
3+
docker run -d --name mina-frontend -p 8070:80 o1labs/mina-rust-frontend:latest
4+
5+
# Access the dashboard at http://localhost:8070

‎website/docs/developers/scripts/frontend/install-angular-cli.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Install Angular CLI globally
2+
npm install -g @angular/cli@19
3+
4+
# Verify installation
5+
ng version

‎website/docs/developers/scripts/frontend/install-dependencies.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Navigate to frontend directory
2+
cd mina-rust/frontend
3+
4+
# Install npm dependencies
5+
npm install

0 commit comments

Comments
 (0)