Skip to content

Commit 852eafc

Browse files
idalithbfubhy
idalithb
and
fubhy
authored
docs updates (#1)
* docs updates * Update src/content/docs/Quick Starts/quick-start-local.md * draft 1 --------- Co-authored-by: Sebastian Lorenz <fubhy@fubhy.com>
1 parent 636d526 commit 852eafc

10 files changed

Lines changed: 1769 additions & 39 deletions

File tree

‎astro.config.ts‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
import { defineConfig } from 'astro/config';
2-
import tailwindcss from '@tailwindcss/vite';
3-
import starlight from '@astrojs/starlight';
1+
import { defineConfig } from "astro/config";
2+
import tailwindcss from "@tailwindcss/vite";
3+
import starlight from "@astrojs/starlight";
44

55
// https://astro.build/config
66
export default defineConfig({
7-
integrations: [
8-
starlight({
9-
title: 'Amp',
10-
}),
11-
],
12-
vite: {
13-
plugins: [tailwindcss()],
14-
},
7+
integrations: [
8+
starlight({
9+
title: "Amp",
10+
}),
11+
],
12+
vite: {
13+
plugins: [tailwindcss()],
14+
},
1515
});

‎package.json‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,18 @@
88
"astro": "astro"
99
},
1010
"dependencies": {
11-
"@astrojs/starlight": "^0.36.0",
12-
"astro": "^5.14.4"
11+
"@astrojs/starlight": "^0.36.1",
12+
"astro": "^5.15.1"
1313
},
1414
"packageManager": "pnpm@10.18.2+sha512.9fb969fa749b3ade6035e0f109f0b8a60b5d08a1a87fdf72e337da90dcc93336e2280ca4e44f2358a649b83c17959e9993e777c2080879f3801e6f0d999ad3dd",
1515
"devDependencies": {
1616
"@tailwindcss/vite": "^4.1.14",
17+
"@typescript-eslint/eslint-plugin": "^8.46.2",
18+
"@typescript-eslint/parser": "^8.46.2",
19+
"astro-eslint-parser": "^1.2.2",
20+
"eslint": "^9.38.0",
21+
"eslint-plugin-astro": "^1.4.0",
22+
"prettier": "^3.6.2",
1723
"tailwindcss": "^4.1.14"
1824
}
1925
}

‎pnpm-lock.yaml‎

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

‎src/content/docs/How-to Guides/serverless-mode.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: How to Extract Data Using Serverless Mode
3+
description: Learn how to run a one-off extraction
4+
slug: how-to/serverless-extraction
5+
command: ampd dump
6+
category: extraction
7+
---
8+
9+
## Goal
10+
11+
Extract blockchain dataset data on demand using Amp’s serverless mode (ampd dump).
12+
13+
### When to Use
14+
15+
- One-time or scheduled data extraction
16+
- Bootstrapping datasets
17+
- Verifying dataset configuration
18+
- CI/CD or event-driven jobs
19+
20+
## Steps
21+
22+
1. Choose the dataset
23+
24+
Identify your dataset name or manifest path (e.g., eth_mainnet).
25+
26+
2. Run a simple extraction
27+
28+
```bash
29+
ampd dump --dataset eth_mainnet
30+
```
31+
32+
3. Run in parallel for speed
33+
34+
```bash
35+
ampd dump --dataset eth_mainnet --n-jobs 4
36+
```
37+
38+
4. Extract a range of blocks
39+
40+
```bash
41+
ampd dump --dataset eth_mainnet --end-block 4000000
42+
```
43+
44+
5. Resume or start fresh
45+
Resume automatically (default)
46+
47+
Start fresh:
48+
49+
```bash
50+
ampd dump --dataset eth_mainnet --fresh
51+
```
52+
53+
6. Automate the extraction
54+
Run periodically (e.g., every 30 minutes):
55+
56+
```bash
57+
ampd dump --dataset eth_mainnet --run-every-mins 30
58+
```
59+
60+
## Expected Outcome
61+
62+
Amp runs an ephemeral extraction job:
63+
64+
1. Loads dataset config
65+
2. Extracts blockchain data
66+
3. Writes Parquet files
67+
4. Updates progress in metadata DB
68+
5. Exits when done

‎src/content/docs/How-to Guides/single-node.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: How to Run Amp in Development Mode
3+
slug: how-to/dev-mode
4+
command: ampd dev
5+
category: local-testing
6+
---
7+
8+
## Goal
9+
10+
Run Amp locally with all components (server, controller, and worker) in a single process.
11+
12+
### When to Use
13+
14+
- Local testing
15+
- CI/CD validation
16+
- Quick prototyping
17+
- Learning Amp
18+
19+
## Steps
20+
21+
1. Start development mode
22+
23+
```bash
24+
ampd dev
25+
```
26+
27+
### Amp starts:
28+
29+
- Query servers (Arrow Flight + JSON Lines)
30+
- Controller (Admin API)
31+
- Embedded worker (`node-id: worker`)
32+
33+
2. Schedule a job via API
34+
35+
```bash
36+
curl -X POST http://localhost:1610/datasets/eth_mainnet/dump \
37+
-H "Content-Type: application/json" \
38+
-d '{"end_block": 1000000}'
39+
```
40+
41+
3. Query the extracted data
42+
43+
```bash
44+
curl -X POST http://localhost:1603 \
45+
--data "SELECT COUNT(\*) FROM eth_mainnet.blocks
46+
```
47+
48+
## Expected Outcome
49+
50+
All components run locally and communicate over the metadata DB.
51+
52+
Jobs execute automatically in the embedded worker.
53+
54+
### Limitations
55+
56+
- Not production-ready
57+
- No isolation or scaling
58+
- Shared CPU/memory between services

‎src/content/docs/Quick Starts/quick-start-ampup.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Quickstart Ampup
3+
description: Build with Amp with Ampup
4+
slug: quickstart/ampup
5+
command: ampup
6+
category: quickstart
7+
---
8+
9+
This quickstart helps you jump start Amp locally
10+
11+
## Prerequisites
12+
13+
1. Repository Setup
14+
15+
```bash
16+
git clone <repository-url>
17+
cd <repository-name>`
18+
```
19+
20+
2. PostgreSQL database Setup
21+
22+
You need this database to store metadata.
23+
The easiest way to set this up is by using **Docker**.
24+
25+
### Steps
26+
27+
1. From the root of the `amp` repository, start the PostgreSQL service:
28+
29+
```bash
30+
docker-compose up -d db
31+
```
32+
33+
This command starts PostgreSQL in the background.
34+
35+
2. Verify that the PostgreSQL container is running:
36+
37+
```bash
38+
docker ps | grep postgres
39+
```
40+
41+
## Step-by-step
42+
43+
### Installation via Ampup
44+
45+
1. Use `ampup`, the official version manager and installer:
46+
47+
```sh
48+
curl --proto '=https' --tlsv1.2 -sSf https://ampup.sh/install | sh
49+
```
50+
51+
This will install `ampup` and the latest version of `ampd`. You may need to restart your terminal or run `source ~/.zshenv` (or your shell's equivalent) to update your PATH.
52+
53+
Once installed, you can manage `ampd` versions:
54+
55+
```sh
56+
# Install or update to the latest version
57+
ampup install
58+
59+
# Switch between installed versions
60+
ampup use
61+
```
62+
63+
> For more details and advanced options, see `ampup --help`.
64+
65+
### Installation via Nix
66+
67+
> This will be supported once the source repository has been released
68+
69+
For Nix users, `ampd` is available as a flake:
70+
71+
```sh
72+
# Run directly without installing
73+
nix run github:edgeandnode/amp
74+
75+
# Install to your profile
76+
nix profile install github:edgeandnode/amp
77+
78+
# Try it out temporarily
79+
nix shell github:edgeandnode/amp -c ampd --version
80+
```
81+
82+
#### Add Configurations
83+
84+
You can also add amp to your NixOS or home-manager configuration:
85+
86+
```nix
87+
{
88+
inputs = {
89+
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
90+
amp = {
91+
url = "github:edgeandnode/amp";
92+
inputs.nixpkgs.follows = "nixpkgs";
93+
};
94+
};
95+
96+
outputs = { nixpkgs, amp, ... }: {
97+
# NixOS configuration
98+
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
99+
# ...
100+
environment.systemPackages = [
101+
amp.packages.${system}.ampd
102+
];
103+
};
104+
105+
# Or home-manager configuration
106+
home.packages = [
107+
amp.packages.${system}.ampd
108+
];
109+
};
110+
}
111+
```
112+
113+
> Note: Nix handles version management, so `ampup` is not needed for Nix users.
114+
115+
### Building from Source (Manual)
116+
117+
> This will be supported once the source repository has been released
118+
119+
If you prefer to build manually without using `ampup`:
120+
121+
```sh
122+
cargo build --release -p ampd
123+
```
124+
125+
The binary will be available at `target/release/ampd`.

‎src/content/docs/Quick Starts/quick-start-local.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
title: Quickstart Locally
3+
description: Build with Amp locally
4+
slug: quickstart/locally
5+
command: docker-compose
6+
category: quickstart
7+
---
8+
9+
This quickstart helps you jump start Amp locally
10+
11+
## Prerequisites
12+
13+
1. Repository Setup
14+
15+
```bash
16+
git clone <repository-url>
17+
cd <repository-name>`
18+
```
19+
20+
2. PostgreSQL database setup
21+
22+
You need this database to store metadata.
23+
The easiest way to set this up is by using **Docker**.
24+
25+
### Steps
26+
27+
1. From the root of the `amp` repository, start the PostgreSQL service:
28+
29+
```bash
30+
docker-compose up -d db
31+
```
32+
33+
This command starts PostgreSQL in the background.
34+
35+
2. Verify that the PostgreSQL container is running:
36+
37+
```bash
38+
docker ps | grep postgres
39+
```
40+
41+
## Step-by-Step
42+
43+
1. Navigate to the amp repository
44+
45+
```bash
46+
cd /path/to/amp`
47+
```
48+
49+
2. Build the release binary
50+
51+
```bash
52+
cargo build --release -p ampd
53+
```
54+
55+
3. Make it available in our PATH (choose one method):
56+
57+
### Method A
58+
59+
#### Create a symlink in a directory already in PATH
60+
61+
```bash
62+
sudo ln -sf $(pwd)/target/release/ampd /usr/local/bin/ampd
63+
```
64+
65+
### Method B
66+
67+
- Add the target directory to our PATH
68+
69+
```bash
70+
export PATH="$(pwd)/target/release:$PATH"
71+
```
72+
73+
- Add this to ~/.bashrc, ~/.zshenv, etc. to persist
74+
75+
4. Verify installation:
76+
77+
```bash
78+
ampd --version
79+
```

0 commit comments

Comments
 (0)