Bigcapital: self-hosted double-entry accounting with an AGPL licence

The problem Bigcapital addresses for small and medium businesses

Most accounting tools assume the books live on someone else's servers. Bigcapital takes the opposite position. The README describes it as "a smart and open-source accounting and inventory software" that keeps business finances in place and automates accounting processes to produce financial statements and reports. The audience is the small or medium business that wants double-entry bookkeeping, inventory tracking and reporting without handing the ledger to a SaaS vendor.

The second audience is the developer. The README has a section called Headless Accounting, which says you can integrate the Bigcapital API with your system to organize transactions in a double-entry system. That is a different use case from the accountant clicking through a web app: it means a product team can post journal entries from their own application and let Bigcapital hold the chart of accounts and generate the statements.

It is not a tax filing service and it is not a payroll system. Nothing in the README claims either. If your requirement is a jurisdiction-specific filing workflow, this is not the tool the repository describes.

How the pieces fit together: server, webapp and the surrounding services

The repository is a Lerna monorepo with pnpm workspaces. The package.json names the workspace bigcapital-monorepo and defines scoped scripts against packages called @bigcapital/server, @bigcapital/webapp, @bigcapital/utils, @bigcapital/pdf-templates, @bigcapital/email-components and @bigcapital/sdk-ts. The server and the webapp are separate packages, so you can build the API without the front end.

The runtime dependencies are visible in docker-compose.yml. That file defines MariaDB for the relational data, Redis, Gotenberg for PDF rendering and ClickHouse for analytics. The file itself carries a warning that it is a development version, that it exposes sensitive ports and mounts code volumes, and that it should be avoided in production. The production file is docker-compose.prod.yml.

The database layout is multi-tenant at the schema level. The environment example defines SYSTEM_DB_NAME=bigcapital_system and TENANT_DB_NAME_PERFIX=bigcapital_tenant_. The spelling of PERFIX is as it appears in the file. Each tenant gets its own database with that prefix, and the migration scripts are split accordingly: system:migrate:latest for the system database and tenants:migrate:latest for the tenant databases. That split is the single most important operational detail in the repository, because a half-migrated tenant database is the failure mode you have to plan for.

ClickHouse appears under an environment variable CLICKHOUSE_DB with a default of bigcapital_analytics, which suggests analytics queries are routed away from MariaDB rather than run against the transactional tables.

Installing Bigcapital self hosted with Docker Compose

The README points self-hosting at a Docker guide on docs.bigcapital.app and does not repeat the steps inline. What the repository does give you is the compose files and the environment template. Start by copying .env.example to .env and filling in the required values. The one the file marks as required is the JWT signing secret, and the file gives the command to produce it.

openssl rand -base64 48

Paste the output into APP_JWT_SECRET. The database defaults in the template are DB_USER=bigcapital, DB_PASSWORD=bigcapital, DB_ROOT_PASSWORD=root and DB_HOST=localhost; change them before anything is reachable from outside the host. BASE_URL=http://example.com also needs to be your real origin.

Then bring the stack up. For a development checkout the repository provides docker-compose.yml, and the README warns through the file header that this is not the production file.

docker compose up -d

For production the repository ships docker-compose.prod.yml, which is the file to use on a real host. After the containers are healthy, apply migrations. The root package.json exposes both scopes through Lerna, so from a checkout you would run:

pnpm run system:migrate:latest
pnpm run tenants:migrate:latest

Sign-up is controlled by environment variables. SIGNUP_DISABLED defaults to false, and SIGNUP_ALLOWED_DOMAINS and SIGNUP_ALLOWED_EMAILS restrict who can register. On a public instance, create your first account, then set SIGNUP_DISABLED=true and restart. Confirm the account was created before you lock registration down, because the README does not document a recovery path for a locked-out instance.

If you are driving the ledger from your own code rather than the web app, the README links a Postman workspace for the API and the monorepo ships an @bigcapital/sdk-ts package. Note the throttle defaults before you write an importer: THROTTLE_GLOBAL_LIMIT=300 over THROTTLE_GLOBAL_TTL=60000, and THROTTLE_AUTH_LIMIT=30. The environment file itself suggests raising THROTTLE_GLOBAL_LIMIT temporarily for a bulk import or an API-scripted migration.

Where Bigcapital will disappoint you

The compose file is honest about its own limits, and you should take that warning literally. The development compose file publishes MariaDB on 3306, Redis on 6379 and the Gotenberg port mapping 9000:3000. Running that file on a host with a public interface puts a database and a cache on the internet. The repository gives you docker-compose.prod.yml precisely because the development file is not a deployment artifact.

The second limitation is operational weight. This is not a single binary. A working instance involves MariaDB, Redis, ClickHouse and Gotenberg, plus the server and the webapp. Each one has its own backup story, its own upgrade path and its own way of failing. A small business without anyone comfortable with containers will spend more time on the stack than on the books.

The third is the migration split. Because system and tenant data live in separate databases with separate migration commands, an upgrade is a two-step operation that can succeed halfway. The repository exposes system:migrate:rollback and tenants:migrate:rollback, so rollback exists at the command level, but the README does not document a coordinated rollback procedure or what happens to tenant databases if the system migration fails. Treat that as unverified and test it on a copy first.

Finally, the AGPL. If you modify Bigcapital and let users interact with it over a network, the licence's network clause is the part your legal team needs to read. The repository ships a DISCLAIMER file alongside LICENSE, which is worth reading before you build a commercial product on top.

Bigcapital compared with Akaunting and with hosted suites

The comparison people search for is Akaunting versus Bigcapital, and the difference is architectural rather than cosmetic. Akaunting is a PHP application built around the Laravel ecosystem, which means a conventional LAMP deployment and a large pool of PHP developers who can read the source. Bigcapital is TypeScript across the monorepo, with a Lerna and pnpm workspace, a separate server and webapp package, and an SDK package for programmatic access.

The practical consequence is who can maintain it. If your team writes PHP, Akaunting is closer to the skills you already have. If your team writes TypeScript and wants to call the ledger from a Node service, Bigcapital's split between @bigcapital/server and @bigcapital/sdk-ts is the more natural fit, and the README's headless accounting section is aimed squarely at that.

The second comparison is against the hosted suites the README names as alternatives: QuickBooks, Xero and Wave. Those give you a vendor who runs the database, handles the backups and takes responsibility for uptime. Bigcapital gives you the opposite trade. You keep the data and the reporting pipeline, and you own every failure. The README also links a hosted option at my.bigcapital.app, so the project is not purely self-hosted, but the repository itself is the self-hosted path.

One thing the README does not do is claim feature parity with any of them. There is no comparison table and no migration guide from QuickBooks or Xero. If you are moving existing books, you are writing that import yourself against the API.

Maintenance status, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-27. Releases are frequent and small: v0.25.32 on 2026-08-19, v0.25.33 on 2026-08-24 and v0.25.34 on 2026-08-27. That cadence suggests patch-level changes rather than long-stable milestones, and it means the upgrade cost is not a once-a-year project. If you track releases, expect to run the migration commands regularly rather than annually.

The licence is AGPL-3.0, stated in both the repository metadata and the README's self-hosted section. The practical implication for a self-hoster running the software unmodified for internal bookkeeping is usually straightforward. The implication for anyone embedding Bigcapital in a product they distribute or expose to users over a network is not, and that is a question for your own counsel rather than for this article. The repository includes a DISCLAIMER file in addition to LICENSE.

Upgrade cost also includes the surrounding services. The compose file pins gotenberg/gotenberg:7 and clickhouse/clickhouse-server:24.8, so a Bigcapital upgrade can drag a ClickHouse major version with it. Back up the system database and every tenant database before you run system:migrate:latest, and keep the rollback commands system:migrate:rollback and tenants:migrate:rollback within reach.

Editorial conclusion

Adopt Bigcapital if you want the general ledger, inventory and reporting inside your own infrastructure and you can run MariaDB, Redis, ClickHouse and Gotenberg yourself. Do not adopt it if you need a vendor to hold the licence for a closed product you resell, or if nobody on the team can operate a multi-service Docker stack. Before committing, generate APP_JWT_SECRET with openssl rand -base64 48, set SIGNUP_DISABLED=false only long enough to create the first user, and confirm the migration scripts system:migrate:latest and tenants:migrate:latest run cleanly against your own database.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes