This doc is a development guide for how engineers can contribute to this project.
- macOS
- Docker Desktop
- Go 1.24 or later
- Node.js 18 and nvm
- npm
- Schemahero (must rename the binary to
schemaheroand put on path) - A SQL DB editor available. Confider Beekeeper Studio if you don't already have one available
Before starting, ensure you have the following secrets configured locally on your computer:
ANTHROPIC_API_KEY: Get your own key (Create a new API key in Anthropic Console)GROQ_API_KEY: Get your own key (Get a new API key from groq.com)VOYAGE_API_KEY: Get your own key (Generate new key)CHARTSMITH_PG_URI=postgresql://postgres:password@localhost:5432/chartsmith?sslmode=disableCHARTSMITH_CENTRIFUGO_ADDRESS=http://localhost:8000/apiCHARTSMITH_CENTRIFUGO_API_KEY=api_key(Already set)CHARTSMITH_TOKEN_ENCRYPTION=(Can ignore)CHARTSMITH_SLACK_TOKEN=(Can ignore)CHARTSMITH_SLACK_CHANNEL=(Can ignore)
You should also create a .env.local file in the chartsmith-app directory with some of the same content. You will update this with your Anthropic API key, and your Google Client secret information.
NEXT_PUBLIC_GOOGLE_CLIENT_ID=730758876435-8v7frmnqtt7k7v65edpc6u3hso9olqbe.apps.googleusercontent.com
NEXT_PUBLIC_GOOGLE_REDIRECT_URI=http://localhost:3000/auth/google
GOOGLE_CLIENT_SECRET=<get from 1password>
HMAC_SECRET=not-secure
CENTRIFUGO_TOKEN_HMAC_SECRET=change.me
NEXT_PUBLIC_CENTRIFUGO_ADDRESS=ws://localhost:8000/connection/websocket
TOKEN_ENCRYPTION=H5984PaaBSbFZTMKjHiqshqRCG4dg49JAs0dDdLbvEs=
NEXT_PUBLIC_REPLICATED_REDIRECT_URI=https://vendor-web-<youruser>.okteto.repldev.com/chartsmith-login?redirect_uri=https://chartsmith-app-<youruser>.okteto.repldev.com/auth/replicated
ANTHROPIC_API_KEY=
NEXT_PUBLIC_ENABLE_TEST_AUTH=true
ENABLE_TEST_AUTH=true
NEXT_PUBLIC_API_ENDPOINT=http://localhost:3000/api
-
Start the Development Environment
cd hack/chartsmith-dev docker compose up -d -
Open Four Terminal Windows
You'll need to run multiple services simultaneously. Open four separate terminal windows and navigate to the project root in each.
-
Terminal 1: Frontend Development
cd chartsmith-app npm install npm run devThis starts the frontend development server.
-
Terminal 2: Backend Worker
make run-worker
This runs the backend worker service.
-
Terminal 3: Database Schema
make schema
This deploys the Schemahero migrations to set up the database schema.
-
Terminal 4: Bootstrap Chart Data
make bootstrap
This is a critical step that initializes the chart data in the database. Without this step, the application won't have the necessary template data to function properly.
-
Admin Access
The first user to log in will automatically be granted admin privileges and bypass the waitlist. You can log in at: http://localhost:3000/login?test-auth=true
-
Terminal 5: Claude Integration (optional)
# Use Claude for development assistance
- To rebuild the worker:
make run-worker
If you encounter any issues:
- Ensure Docker is running and all containers are up
- Verify all required secrets are properly configured
- Check that Schemahero is installed and accessible in your PATH
- Make sure all dependencies are installed (both Go and npm packages)
- If you get an error
ERROR: type "vector" does not existwhen runningmake schema, you can manually enable the PGVector extension:Or simply run the Make target that handles this:docker exec -it chartsmith-dev-postgres-1 psql -U postgres -d chartsmith -c "CREATE EXTENSION IF NOT EXISTS vector;"
After enabling the extension, runmake pgvector
make schemaagain (though it now automatically runs the pgvector target as a prerequisite).
- Make changes to the code
- The frontend will automatically reload with changes
- The worker will need to be restarted if you make backend changes
- Use Claude for code assistance and development guidance
- The development environment uses PostgreSQL running in Docker
- Schemahero is used for database migrations
- The frontend runs on the default Next.js port
- The worker runs on a separate process
For detailed instructions on developing the VS Code extension, see chartsmith-extension/DEVELOPMENT.md.
This guide covers:
- Building and installing the extension from a VSIX file
- Configuring endpoints for local development
- Enabling development mode
- Debugging with the developer console
- Testing extension features with built-in commands
Run the complete validation suite before opening a pull request or cutting a release:
make validateThis renders the database migrations, runs the Go tests, installs the frontend dependencies, runs the frontend unit tests, and builds the frontend.
Releases require Docker, the GitHub CLI, the 1Password CLI, the AWS CLI, and Kustomize. Authenticate the GitHub CLI with GITHUB_TOKEN and provide the production automation service-account token as OP_SERVICE_ACCOUNT_PRODUCTION.
make release version=[patch|minor|major]You can also pass an explicit version. The release script creates the tag, builds and pushes both container images to the staging, production, and Docker Hub registries, updates the staging GitOps manifests, and creates the GitHub release.
Promote an existing version to production without rebuilding its images:
make production version=1.2.3