Skip to content

Commit e51bc8b

Browse files
author
Ignacio Van Droogenbroeck
committed
docs: Complete documentation site setup with Arc branding
- Remove default Docusaurus tutorials and emojis from all docs - Add capitalized category labels for all sections - Update landing page with Arc performance metrics (36.43s, 2.01M RPS, 205+ stars) - Replace placeholder images with performance numbers (36.43s, 2.01M, S3) - Update all internal links to use /arc base path - Add GitHub Actions deployment workflow with Tailscale - Configure Traefik reverse proxy with Let's Encrypt SSL - Update README with technology stack and contribution guidelines - Fix benchmarks: 36.43s cold run, 107.66s total, updated comparison multipliers - Add flexible storage description: Local/MinIO/S3/GCS support Deployment ready for docs.basekick.net
1 parent 462fe43 commit e51bc8b

35 files changed

Lines changed: 524 additions & 706 deletions

‎.github/workflows/deploy.yml‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
name: Deploy Docs to Server
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v3
15+
16+
- name: Setup Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: '20'
20+
cache: 'npm'
21+
22+
- name: Install dependencies
23+
run: npm ci
24+
25+
- name: Build
26+
run: npm run build
27+
28+
- name: Set up Tailscale
29+
run: |
30+
set -x
31+
curl -fsSL https://tailscale.com/install.sh | sh
32+
if [ $? -ne 0 ]; then echo "Tailscale installation failed"; exit 1; fi
33+
34+
sudo tailscale up --authkey=${{ secrets.TAILSCALE_AUTH_KEY }} --hostname=github-actions-docs-runner
35+
if [ $? -ne 0 ]; then echo "Tailscale up failed"; exit 1; fi
36+
37+
tailscale status
38+
if [ $? -ne 0 ]; then echo "Tailscale status check failed"; exit 1; fi
39+
shell: bash
40+
41+
- name: Set up SSH
42+
run: |
43+
set -x
44+
mkdir -p ~/.ssh
45+
if [ $? -ne 0 ]; then echo "Failed to create .ssh directory"; exit 1; fi
46+
47+
echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
48+
if [ $? -ne 0 ]; then echo "Failed to write SSH private key"; exit 1; fi
49+
50+
chmod 600 ~/.ssh/id_rsa
51+
if [ $? -ne 0 ]; then echo "Failed to set permissions on SSH private key"; exit 1; fi
52+
53+
eval $(ssh-agent -s)
54+
if [ $? -ne 0 ]; then echo "Failed to start ssh-agent"; exit 1; fi
55+
56+
ssh-add ~/.ssh/id_rsa
57+
if [ $? -ne 0 ]; then echo "Failed to add SSH key to agent"; exit 1; fi
58+
shell: bash
59+
60+
- name: Check DNS Resolution
61+
run: nslookup ${{ secrets.DEPLOY_HOST }}
62+
shell: bash
63+
64+
- name: Check Network Connectivity
65+
run: ping -c 4 ${{ secrets.DEPLOY_HOST }}
66+
shell: bash
67+
68+
- name: Add host to known_hosts
69+
run: |
70+
set -x
71+
echo "Adding host to known_hosts..."
72+
mkdir -p ~/.ssh
73+
touch ~/.ssh/known_hosts
74+
ssh-keyscan -v -H ${{ secrets.DEPLOY_HOST }} >> ~/.ssh/known_hosts
75+
if [ $? -ne 0 ]; then echo "Failed to add host to known_hosts"; exit 1; fi
76+
shell: bash
77+
78+
- name: Test SSH Connection
79+
run: |
80+
set -x
81+
echo "Testing SSH connection..."
82+
ssh -vvv ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }} whoami
83+
if [ $? -ne 0 ]; then echo "SSH connection test failed"; exit 1; fi
84+
shell: bash
85+
86+
- name: Sync docs files to remote host
87+
run: |
88+
set -x
89+
echo "Syncing docs.basekick.net files to remote host..."
90+
ssh ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }} "sudo mkdir -p ${{ secrets.DEPLOY_PATH }} && sudo chown ${{ secrets.DEPLOY_USER }}:${{ secrets.DEPLOY_USER }} ${{ secrets.DEPLOY_PATH }}"
91+
rsync -avz --checksum --delete \
92+
--exclude '.git' \
93+
--exclude 'node_modules' \
94+
--exclude '.github' \
95+
--exclude '*.log' \
96+
--exclude '.DS_Store' \
97+
--stats \
98+
./build/ ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}:${{ secrets.DEPLOY_PATH }}
99+
if [ $? -ne 0 ]; then echo "File sync failed"; exit 1; fi
100+
shell: bash
101+
102+
- name: Deploy docs with Docker Compose
103+
run: |
104+
set -x
105+
echo "Deploying docs.basekick.net (Docusaurus static site)..."
106+
DEPLOY_DIR=$(dirname ${{ secrets.DEPLOY_PATH }})
107+
ssh ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }} << EOF
108+
cd \$DEPLOY_DIR
109+
110+
# Ensure external Docker network exists
111+
sudo docker network create traefik || true
112+
113+
# Restart docs container
114+
sudo docker compose up -d docs
115+
116+
# Touch deployment timestamp
117+
touch .last-deploy
118+
119+
# Show container status
120+
sudo docker ps | grep docs
121+
EOF
122+
if [ $? -ne 0 ]; then echo "Deployment failed"; exit 1; fi
123+
shell: bash

‎README.md‎

Lines changed: 130 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,154 @@
1-
# Website
1+
# Arc Documentation
22

3-
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
3+
Official documentation for [Arc](https://github.com/basekick-labs/arc) - the fastest time-series database in ClickBench.
44

5-
## Installation
5+
## About
6+
7+
This repository contains the documentation website for Arc, a high-performance time-series data warehouse built on DuckDB and Parquet. Arc achieves 36.43s on ClickBench (99.9M rows) and delivers 2.01M records/sec ingestion.
8+
9+
Visit the live documentation at [docs.basekick.net](https://docs.basekick.net)
10+
11+
## Technology Stack
12+
13+
- **Docusaurus 3.9.1** - Modern static site generator built with React
14+
- **TypeScript** - Type-safe documentation and components
15+
- **Markdown/MDX** - Documentation content format
16+
- **GitHub Actions** - Automated deployment pipeline
17+
- **Nginx** - Static file serving in production
18+
- **Traefik** - Reverse proxy with Let's Encrypt SSL
19+
20+
## Local Development
21+
22+
### Prerequisites
23+
24+
- Node.js 20+
25+
- npm or yarn
26+
27+
### Installation
628

729
```bash
8-
yarn
30+
npm install
931
```
1032

11-
## Local Development
33+
### Start Development Server
1234

1335
```bash
14-
yarn start
36+
npm start
1537
```
1638

17-
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
39+
This starts a local development server at `http://localhost:3000` with hot reloading.
1840

19-
## Build
41+
### Build for Production
2042

2143
```bash
22-
yarn build
44+
npm run build
2345
```
2446

25-
This command generates static content into the `build` directory and can be served using any static contents hosting service.
47+
Generates static content in the `build/` directory ready for deployment.
2648

27-
## Deployment
49+
## Documentation Structure
50+
51+
```
52+
docs/
53+
├── intro.md # Getting started
54+
├── getting-started.md # Quick start guide
55+
├── installation/ # Docker and native setup
56+
├── configuration/ # Configuration guides
57+
├── performance/ # ClickBench benchmarks
58+
├── api-reference/ # API documentation
59+
├── integrations/ # Superset, Telegraf, etc.
60+
└── advanced/ # WAL, compaction features
61+
```
62+
63+
## Contributing
64+
65+
We welcome contributions to improve the documentation!
66+
67+
### How to Contribute
68+
69+
1. **Fork the repository**
70+
```bash
71+
git clone https://github.com/basekick-labs/docs.basekick.net.git
72+
cd docs.basekick.net
73+
```
74+
75+
2. **Create a branch**
76+
```bash
77+
git checkout -b docs/improve-installation-guide
78+
```
2879

29-
Using SSH:
80+
3. **Make your changes**
81+
- Edit markdown files in `docs/`
82+
- Test locally with `npm start`
83+
- Verify the build with `npm run build`
84+
85+
4. **Commit and push**
86+
```bash
87+
git add .
88+
git commit -m "docs: improve installation guide with examples"
89+
git push origin docs/improve-installation-guide
90+
```
91+
92+
5. **Create a Pull Request**
93+
- Open a PR on GitHub
94+
- Describe your changes
95+
- Link any related issues
96+
97+
### Documentation Guidelines
98+
99+
- **No emojis** - Keep documentation professional and accessible
100+
- **Clear headings** - Use descriptive section titles
101+
- **Code examples** - Include working code snippets
102+
- **Links** - Use `/arc/page-name` for internal links
103+
- **Images** - Store in `static/img/` and reference with `/img/filename`
104+
105+
### Testing Your Changes
106+
107+
Before submitting:
30108

31109
```bash
32-
USE_SSH=true yarn deploy
110+
# Check for broken links
111+
npm run build
112+
113+
# Test locally
114+
npm start
33115
```
34116

35-
Not using SSH:
117+
## Deployment
118+
119+
This repository deploys automatically via GitHub Actions when changes are pushed to `main`. The workflow:
120+
121+
1. Builds the Docusaurus site
122+
2. Connects to deployment server via Tailscale VPN
123+
3. Syncs files to `/opt/services/docs.basekick.net`
124+
4. Nginx serves the static site at docs.basekick.net
125+
126+
## Project Structure
36127

37-
```bash
38-
GIT_USER=<Your GitHub username> yarn deploy
39128
```
129+
docs.basekick.net/
130+
├── .github/workflows/ # GitHub Actions
131+
├── docs/ # Documentation content (Markdown)
132+
├── src/
133+
│ ├── components/ # React components
134+
│ ├── css/ # Custom styles
135+
│ └── pages/ # Custom pages (homepage)
136+
├── static/ # Static assets (images, etc.)
137+
├── docusaurus.config.ts # Docusaurus configuration
138+
├── sidebars.ts # Sidebar navigation
139+
└── docker-compose.yml # Production deployment
140+
```
141+
142+
## Support
143+
144+
- Documentation: [docs.basekick.net](https://docs.basekick.net)
145+
- GitHub Issues: [github.com/basekick-labs/arc/issues](https://github.com/basekick-labs/arc/issues)
146+
- Website: [basekick.net](https://basekick.net)
147+
148+
## License
149+
150+
This documentation is part of the Arc project.
151+
152+
---
40153

41-
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
154+
Built by [Basekick Labs](https://basekick.net) with Docusaurus.

‎docker-compose.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
version: '3.8'
2+
3+
services:
4+
docs:
5+
image: nginx:alpine
6+
container_name: docs-basekick-net
7+
restart: unless-stopped
8+
volumes:
9+
- /opt/services/docs.basekick.net:/usr/share/nginx/html:ro
10+
networks:
11+
- traefik
12+
labels:
13+
- "traefik.enable=true"
14+
- "traefik.docker.network=traefik"
15+
- "traefik.http.routers.docs-basekick.rule=Host(`docs.basekick.net`)"
16+
- "traefik.http.routers.docs-basekick.entrypoints=https"
17+
- "traefik.http.routers.docs-basekick.tls=true"
18+
- "traefik.http.routers.docs-basekick.tls.certresolver=letsencrypt"
19+
- "traefik.http.services.docs-basekick.loadbalancer.server.port=80"
20+
21+
networks:
22+
traefik:
23+
external: true

‎docs/advanced/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Advanced",
3+
"position": 7,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Advanced features including Write-Ahead Log and automatic compaction."
7+
}
8+
}

0 commit comments

Comments
 (0)