š¦ Available templates for v0.8.0:baseboards (recommended)
Full-featured Boards application with UI
Frameworks: Next.js, React, TailwindCSS
Features: Authentication, Boards UI, Image Generation
Size: 12.5 MB
basic
Minimal starter for custom apps
Frameworks: Next.js, React
Features: GraphQL Client, Hooks
Size: 45.2 KB
`$3
Upgrade Baseboards installation to a newer version. This updates templates and Docker Compose configurations while preserving your data and settings.
`Options:
| Flag | Description |
|------|-------------|
|
--version | Upgrade to specific version (default: latest) |
| --dry-run | Preview upgrade without making changes |
| --force | Skip confirmation prompts and compatibility warnings |Examples:
`bash
Upgrade to latest version
baseboards upgradeUpgrade to specific version
baseboards upgrade --version 0.8.0Preview what would change
baseboards upgrade --dry-runPreview upgrade to specific version
baseboards upgrade --dry-run --version 0.8.0
`$3
Run diagnostics and show system information. Useful for troubleshooting issues.
`bash
baseboards doctor [directory]
`Checks:
- Docker installation and version
- Docker Compose availability
- Node.js version (for
--app-dev mode)
- Service health status
- Port availability
- Configuration validityExample output:
`
š„ Baseboards DoctorSystem Information:
Platform: darwin (macOS)
Docker: 24.0.2 ā
Docker Compose: 2.18.1 ā
Node.js: 20.5.0 ā
Project Status:
Directory: /Users/user/my-app
Scaffolded: Yes
Mode: Docker (default)
Services:
ā web (healthy)
ā api (healthy)
ā db (healthy)
ā cache (healthy)
Configuration:
Ports: web=3300 api=8800 db=5432 redis=6379
Template: baseboards
Version: 0.8.0
`Template System
Templates are pre-configured frontend applications that work with the Boards backend. They are downloaded on-demand from GitHub Releases and cached locally for offline use.
$3
| Template | Size | Description | Best For |
|----------|------|-------------|----------|
| baseboards | ~12 MB | Full-featured application with authentication, boards UI, and image generation | Quick start, demos, production use |
| basic | ~45 KB | Minimal Next.js starter with GraphQL client and hooks | Custom apps, learning, minimal footprint |
$3
Interactive (recommended):
`bash
baseboards up my-app
You'll be prompted to select a template
`Explicit flag:
`bash
baseboards up my-app --template basic
`$3
Templates are automatically cached in
~/.cache/baseboards/templates/ after first download. This enables:- Offline usage - Work without internet after initial download
- Faster setup - Subsequent projects use cached templates
- Version pinning - Each CLI version caches its compatible templates
Clear cache:
`bash
baseboards templates --refresh
`$3
Choose
baseboards if you want:
- A complete, production-ready application
- Built-in authentication and user management
- Full boards UI with image generation
- Minimal configurationChoose
basic if you want:
- A minimal starting point for custom apps
- Full control over UI/UX design
- Smaller download size
- To learn how Boards worksDevelopment Modes
Baseboards supports two development modes optimized for different workflows.
$3
All services run in Docker containers, including the frontend.
`bash
baseboards up my-app
`Characteristics:
- Frontend runs in Docker with hot reload
- All services orchestrated via Docker Compose
- No Node.js required on host machine
- Best for: Quick testing, demos, production-like environments
How it works:
- Frontend dev server runs inside Docker container
- Changes to
web/ directory trigger hot reload
- Access at http://localhost:3300$3
Backend runs in Docker, frontend runs locally on your machine.
`bash
baseboards up my-app --app-dev
`Characteristics:
- Backend services (API, DB, Redis) run in Docker
- Frontend runs as native dev server on host
- Native package manager integration (npm, pnpm, yarn, bun)
- Best for: Active frontend development, faster iteration
How it works:
1. Backend services start in Docker
2. CLI installs frontend dependencies using your preferred package manager
3. Frontend dev server starts locally
4. Hot reload works natively with your editor/IDE
Prerequisites:
- Node.js 20+
- Package manager (you'll be prompted to select one)
Switching between modes:
You can switch between modes by running
down then up with different flags:`bash
Switch to app-dev mode
baseboards down
baseboards up --app-devSwitch back to Docker mode
baseboards down
baseboards up
`Common Workflows
$3
`bash
Create and start new project
npx @weirdfingers/baseboards up my-boards-appFollow prompts for:
1. Template selection (baseboards or basic)
2. API key entry (Replicate, OpenAI, etc.)
Access the application
open http://localhost:3300
`$3
`bash
Stop services (preserves data)
baseboards downStart again (no re-scaffolding needed)
baseboards upStop and remove all data
baseboards down --volumes
`$3
`bash
View all logs
baseboards logsFollow logs in real-time
baseboards logs -fView specific service
baseboards logs apiLast 2 hours of API logs
baseboards logs api --since 2h
`$3
`bash
Remove project completely
baseboards down --volumes
cd ..
rm -rf my-boards-appClean Docker resources (in project directory)
baseboards cleanFull cleanup including images
baseboards clean --hard
`$3
`bash
Frontend on 3000, API on 8000
baseboards up --ports web=3000 api=8000Just change frontend port
baseboards up --ports web=4000
`$3
For active frontend development:
`bash
1. Start in app-dev mode
baseboards up my-app --app-dev2. Backend runs in Docker (API, DB, Redis)
3. Frontend runs locally (native dev server)
4. Make changes to web/ directory
5. Hot reload works natively
When done, stop services
baseboards down
`For backend development, edit files in
api/ - changes will trigger reload in Docker.Configuration
$3
API keys and configuration are stored in
api/.env:`bash
Provider API keys (JSON format)
BOARDS_GENERATOR_API_KEYS={"REPLICATE_API_KEY":"r8_...","OPENAI_API_KEY":"sk-..."}Database (auto-configured)
POSTGRES_USER=boards
POSTGRES_PASSWORD=
POSTGRES_DB=boardsRedis (auto-configured)
REDIS_PASSWORD=API secrets (auto-configured)
BOARDS_SECRET_KEY=
`Get API keys:
- Replicate: https://replicate.com/account/api-tokens
- OpenAI: https://platform.openai.com/api-keys
- FAL: https://fal.ai/dashboard/keys
- Google: https://makersuite.google.com/app/apikey
$3
`
my-app/
āā api/.env # Environment variables
āā api/config/generators.yaml # Generator providers and models
āā api/config/storage_config.yaml # Storage configuration (local/S3/GCS)
āā compose.yaml # Docker Compose orchestration
āā docker/ # Service-specific Docker configs
`$3
Default ports:
| Service | Port | Description |
|---------|------|-------------|
| web | 3300 | Frontend application |
| api | 8800 | Backend GraphQL API |
| db | 5432 | PostgreSQL (internal only) |
| cache | 6379 | Redis (internal only) |
Custom ports:
`bash
baseboards up --ports web=3000 api=8000
`Port conflicts:
If ports are already in use, you'll see an error. Use
--ports to specify different ports:`bash
Error: port 3300 already in use
baseboards up --ports web=3301
`$3
The backend Docker image version is automatically matched to your CLI version. To use a different backend version:
1. Edit
compose.yaml in your project
2. Change the image tag for the api service:`yaml
services:
api:
image: ghcr.io/weirdfingers/boards-backend:0.8.0 # Pin to specific version
`Advanced Usage
$3
After downloading a template once, you can work offline:
`bash
First time (requires internet)
baseboards up project1 --template basicLater (works offline if cached)
baseboards up project2 --template basic
`Cache location:
~/.cache/baseboards/templates/$3
For automated deployments, specify template explicitly to avoid prompts:
`bash
Non-interactive mode (no prompts)
baseboards up deployment --template baseboardsSet API keys via environment
export BOARDS_GENERATOR_API_KEYS='{"REPLICATE_API_KEY":"r8_..."}'
`$3
For testing or pinning specific backend versions:
`bash
Start project
baseboards up my-appEdit compose.yaml
cd my-app
Change image: ghcr.io/weirdfingers/boards-backend:latest
to image: ghcr.io/weirdfingers/boards-backend:0.7.5
Restart with specific version
baseboards down
baseboards up
`$3
For Boards contributors testing unpublished package changes:
`bash
From monorepo root
cd boardsBuild packages
pnpm buildCreate test project with local packages
pnpm cli up test-app --app-dev --dev-packagesChanges to packages/frontend are reflected immediately
`Note:
--dev-packages requires:
- Running from Boards monorepo
- --app-dev mode enabled
- Monorepo packages built$3
`bash
View available templates and cache status
baseboards templatesRefresh cache (re-download all templates)
baseboards templates --refreshView templates for different version
baseboards templates --version 0.7.0Manually clear cache
rm -rf ~/.cache/baseboards/templates
`Troubleshooting
$3
#### Port Conflicts
Symptoms: Error message "port 3300 already in use"
Solutions:
`bash
Option 1: Stop conflicting service
Find what's using the port
lsof -i :3300 # macOS/Linux
netstat -ano | findstr :3300 # WindowsOption 2: Use different ports
baseboards up --ports web=3301 api=8801
`#### Docker Not Running
Symptoms: "Cannot connect to the Docker daemon"
Solutions:
1. Start Docker Desktop (macOS/Windows)
2. Start Docker Engine (Linux):
sudo systemctl start docker
3. Verify: docker psRun diagnostics:
`bash
baseboards doctor
`#### Template Download Failures
Symptoms: "Failed to download template" or "Network error"
Solutions:
`bash
Check internet connection
ping github.comClear cache and retry
baseboards templates --refreshTry different template
baseboards up my-app --template basicCheck GitHub status
https://www.githubstatus.com/
`#### Permission Errors
Symptoms: "Permission denied" when creating directories
Solutions:
`bash
Ensure you have write permissions
mkdir test-dir && rmdir test-dirTry different directory
baseboards up ~/Documents/my-appLinux: Check Docker group membership
groups # Should include "docker"
sudo usermod -aG docker $USER # Add to docker group
Log out and back in
`#### Database Password Mismatch
Symptoms: "password authentication failed for user boards"
Solution:
`bash
Clean start (removes volumes)
baseboards down --volumes
baseboards up --fresh
`#### Node.js Version Issues (App-Dev Mode)
Symptoms: "Node.js 20+ required for --app-dev mode"
Solutions:
`bash
Check version
node --versionUpgrade Node.js
Using nvm (recommended)
nvm install 20
nvm use 20Or download from https://nodejs.org/
`#### Out of Disk Space
Symptoms: "no space left on device"
Solutions:
`bash
Clean up Docker resources
docker system prune -a --volumesRemove old Baseboards projects
baseboards clean --hard
cd old-project && baseboards down --volumes
`$3
Run diagnostics:
`bash
baseboards doctor
`View logs:
`bash
baseboards logs -f
`Report issues:
- GitHub Issues: https://github.com/weirdfingers/boards/issues
- Include output from
baseboards doctor
- Include relevant logs from baseboards logsDocumentation:
- Full docs: https://baseboards.dev/docs
- API reference: https://baseboards.dev/docs/api
- Guides: https://baseboards.dev/docs/guides
Community:
- Discord: https://discord.gg/rvVuHyuPEx
- GitHub Discussions: https://github.com/weirdfingers/boards/discussions
Community & Social
Join the Weirdfingers community:
- Discord: https://discord.gg/rvVuHyuPEx
- GitHub: https://github.com/weirdfingers/boards
- TikTok: https://www.tiktok.com/@weirdfingers
- X (Twitter): https://x.com/_Weirdfingers_
- YouTube: https://www.youtube.com/@Weirdfingers
- Instagram: https://www.instagram.com/_weirdfingers_/
License
MIT
---
For Contributors
This package is part of the Boards monorepo.
$3
`bash
Install dependencies
pnpm installBuild package
pnpm build
`This will:
1. Run
prepare-templates.js to copy templates from monorepo
2. Build TypeScript with tsup
3. Create dist/ and templates/ directories$3
`bash
Build the package
pnpm buildRun CLI directly
node dist/index.js up test-projectClean up
cd test-project
docker compose down -v
cd ..
rm -rf test-project
`$3
All packages use unified versioning:
`bash
Bump version across all packages
pnpm version 1.2.0 -rBuild
pnpm buildPublish
pnpm publish
`$3
The CLI bundles templates from the monorepo:
-
apps/baseboards ā templates/web/
- packages/backend ā templates/api/Templates are copied during build time via
scripts/prepare-templates.js.When users run
baseboards up`, templates are copied to their machine and Docker Compose orchestrates the services.