Getting Started

Getting Started with BonsAI #

Welcome! This guide will get you up and running with BonsAI development in under 15 minutes using our cloud development environment.

Overview #

BonsAI uses Coder for all development work. Coder provides:

  • ✅ Pre-configured development environment with all tools installed
  • ✅ Consistent setup across the entire team
  • ✅ Powerful cloud resources (no need for a beefy laptop)
  • ✅ Direct access to development databases and services
  • ✅ No more “works on my machine” issues

Prerequisites #

Before you begin, make sure you have:

  • A Google account with @gotofu.com email
  • Access to Coder
  • Access to GitHub
  • Doppler account (for secrets management)

Step 1: Set Up GitHub SSH Access #

  1. Generate an SSH key (if you don’t have one):

    ssh-keygen -t ed25519 -C "your.email@gotofu.com"

  2. Add your public SSH key to GitHub:

    • Copy your public key: cat ~/.ssh/id_ed25519.pub
    • Go to GitHub SSH Keys Settings
    • Click “New SSH key” and paste your public key

Step 2: Create Your Coder Workspace #

  1. Log in to Coder:

  2. Add your SSH key to Coder:

  3. Create a new workspace:

    • Go to Workspaces
    • Click “Create Workspace”
    • Select the dev template
    • Recommended configuration:
      • Instance type: t3.2xlarge (8 vCPU, 32GB RAM)
      • Disk size: 500GB
    • Click “Create Workspace”

  4. Wait for automatic setup:

    • The workspace will automatically:
      • Install Docker, mise, zsh, and development tools
      • Clone the BonsAI repository to ~/bonsai
      • Run mise install and mise run init
    • This takes about 10-15 minutes on first setup
    • ☕ Grab a coffee while it sets up!

Step 3: Complete Authentication #

Once your workspace is ready, you need to authenticate with Doppler and Atlas:

  1. Open a terminal in your Coder workspace

  2. Authenticate with Doppler:

    cd ~/bonsai
mise run doppler-init
    • Select NO when asked to open in browser
    • Visit the URL provided and copy your token
    • Paste the token in the terminal

  3. Authenticate with Atlas (for database migrations):

    mise run atlas-init
    • Select NO when asked to open in browser
    • Visit the URL provided and copy your token
    • Paste the token in the terminal

Step 4: Start Development #

You’re ready to code! Start the development environment:

cd ~/bonsai
mise run dev

This starts all services:

  • Webapp (Next.js frontend)
  • BonsAPI (Rust backend)
  • PostgreSQL database
  • Redis cache
  • RabbitMQ message queue

Step 5: Access Your Development Environment #

Your Coder workspace dashboard provides quick access to all tools:

Main Services #

  • App - The BonsAI web application (port 3000)
  • API Docs (Internal) - Internal API documentation (port 8001)
  • Internal Docs - This documentation site (port 1313)
  • External Docs - User-facing documentation (port 1314)

Development Tools #

  • Swagger Editor - Edit OpenAPI specifications
  • Database - CloudBeaver for database management
  • Docker - Portainer for container management

External Access #

For testing webhooks or external integrations, use ngrok (pre-installed):

ngrok http 3000

See the Webhooks with ngrok guide for details.

Test Data #

To quickly get started with testing invoice processing, download sample invoice data:

Sample Invoice Data

The test data includes:

  • invoices_*/ - Individual invoices in PDF format
  • multi_invoices_*/ - Multi-invoice PDFs for testing autosplit functionality

Use these files to test:

  • Single invoice upload and extraction
  • Batch invoice processing
  • Multi-document autosplit features

Common Development Tasks #

Now that you’re set up, here are the most common tasks you’ll use:

Running Code Quality Checks #

Before committing code, run linters and formatters:

# Run all checks (linting, type checking, tests)
mise run ci

# Just run linters
mise run lint

# Auto-fix formatting issues
mise run fix

Working with the Database # 

# Run database migrations
mise run db:migrate

# Access database via CloudBeaver
# Click "Database" in your Coder workspace dashboard

Creating a Pull Request #

  1. Create a branch (copy the branch name from Linear):

    git checkout -b koki/eng-1234-feature-name

  2. Make your changes and commit:

    git add .
git commit -m "feat: add new feature"

  3. Push and create PR:

    git push -u origin koki/eng-1234-feature-name

See the Development Workflow guide for more details.

Troubleshooting #

If you run into issues:

  • Git/SSH problems? Check Git SSH Troubleshooting
  • Docker issues? Try docker system prune -a to clean up
  • Doppler auth issues? Re-run mise run doppler-init
  • Need help? Ask on Slack or email dev@gotofu.com

Next Steps #

Now that you’re set up, explore these guides:

Ready to code? Follow the Example Workflow guide to see how a complete feature is implemented from start to finish!

Questions? Don’t hesitate to reach out to the team on Slack or at dev@gotofu.com. Welcome to BonsAI! 🎉