by icoretech
🔥 Lightweight, Airbrake/Sentry-compatible, PostgreSQL-based Open Source Error Catcher
# Add to your Claude Code skills
git clone https://github.com/icoretech/airbrokeAirbroke is currently in active development! Using it in production environments is at your own discretion. We appreciate your feedback and support as we work towards a stable release.
Airbroke provides flexibility in deployment options. You can either deploy it from the built source code or use a multiarch Docker image. For Kubernetes deployments, a Helm chart is provided. As Airbroke is a Next.js 16 application, it can be deployed wherever a Node.js server is supported. This includes managed environments such as Vercel, Netlify, and Heroku.
For a production build, you can run:
cp .env.dist .env
No comments yet. Be the first to share your thoughts!
Then edit the .env file to set your own values.
yarn install
yarn build
This will generate a .next build output. Because this repo uses output: "standalone", the runnable server output is in .next/standalone (see the Dockerfile for a working copy strategy / asset layout).
You can also run yarn start to test the production build locally on port 3000.
We publish images for both amd64 and arm64 architectures on ghcr.io but in case you want to build your own image you can do so.
You can build the Docker image with:
docker build --no-cache -t icoretech/airbroke:latest .
You can then run the image locally with:
docker run -p 3000:3000 icoretech/airbroke:latest
While testing on Vercel has not been conducted, Airbroke should be fully compatible.
It's important to keep the following points in mind:
/api/* will be converted into serverless functions, which may introduce potential cold boot time.build-command that runs DB migrations only for VERCEL_ENV=production before building (adjust this in your Vercel project settings if you need a different workflow).AIRBROKE_CORS_ORIGINS to * for quick starts. After your first deploy, set it to your deployed origin (for example https://<project>.vercel.app) and any custom domains.Detailed instructions for this process can also be found in the Prisma deployment guide for Vercel.
The Render Deploy Button uses render.yaml (Render Blueprint). On the free tier, the template runs yarn db:migrate at boot (safe no-op if already applied). Airbroke allows all origins if AIRBROKE_CORS_ORIGINS is unset — once Render assigns your public URL, lock it down in the Render dashboard for production (this controls CORS for /api/v3/notices and /api/sentry/*/envelope).
Railway supports one-click deployments via Templates. Because templates are created and published from within Railway, you’ll need to create a template once and then wire up the button URL.
Steps:
.env.dist).REPLACE_ME above with the template ID.The Deploy to Netlify button is configured via netlify.toml. The build command runs DB migrations only for production deploys.
Because you don't know your final *.netlify.app URL before the first deploy, you can start with AIRBROKE_CORS_ORIGINS=* and then tighten it to your deployed origin (for example https://<site>.netlify.app) and any custom domains.
The Deploy to Heroku button uses app.json to provision add-ons and prompt for required environment variables.
Because you don't know your final *.herokuapp.com URL before the app is created, you can start with AIRBROKE_CORS_ORIGINS=* and then tighten it to your deployed origin (for example https://<app>.herokuapp.com) and any custom domains.
You can deploy Airbroke to Kubernetes using the dedicated Helm chart.
The Helm chart includes a values.yaml file with some default values that you can override with your own. It also includes a pgBouncer chart as optional dependency.
When using Helm we recommend using a GitOps approach to deploy your application(s), such as Flux.
Please find more information about the Helm chart in the dedicated repository: icoretech/charts
For users who prefer Docker Compose for managing multi-container Docker applications, a docker-compose.yml file is provided at the root of the repository.
To get started, make sure you have Docker and Docker Compose installed on your system. Then, you can start the application using the following command in the terminal:
make build
make run
You can override the default values in the docker-compose.yml file by creating a docker-compose.override.yml file in the same directory. This file is ignored by Git and will not be committed to the repository.
Please view all the available configuration variables in the .env.dist file.
Airbroke requires DATABASE_URL at runtime. DIRECT_URL is required when you need a direct database connection for migrations (for example, when DATABASE_URL goes through PgBouncer or a data proxy). Some examples:
# Example Connection to Prisma Data Proxy
DATABASE_URL="prisma://__HOST__/?api_key=__KEY__"
# Example Connection to PostgreSQL
DATABASE_URL="postgresql://__USER__:__PASSWORD__@__HOST__:__PORT__/__DATABASE__?connection_limit=20&pool_timeout=10&application_name=airbroke"
# Direct connection to the database, used for migrations
DIRECT_URL="postgresql://__USER__:__PASSWORD__@__HOST__:__PORT__/__DATABASE__"
The optimal connection pool size without pgBouncer (connection_limit) can be calculated using the following formula:
connection_limit = (num_physical_cpus * 2 + 1) ÷ number_of_application_instances
For a system with 8 CPU cores and 3 application instances, the calculation would proceed as follows:
connection_limit = (8 * 2 + 1) ÷ 3
connection_limit = (16 + 1) ÷ 3
connection_limit = 17 ÷ 3
connection_limit ≈ 5.67
Since connection_limit must be an integer, it should be rounded down to the nearest whole number. In this scenario, each of the 3 application instances should have a connection_limit of 5.
This limit can be set in your connection strings.
After deployment, you should be able to