Skip to main content
The Bigcapital setup script provides the fastest way to deploy Bigcapital on your own server. This interactive script automates the entire deployment process including downloading configuration files, managing environment variables, and controlling Docker containers.
The setup script is the recommended way to self-host Bigcapital for most users. It handles all the complexity of Docker deployment through a simple interactive menu.

​
Prerequisites

Before running the setup script, ensure you have the following installed on your server:
  • Docker (latest version)
  • Docker Compose (either docker-compose or docker compose plugin)
  • Git
  • curl

​
Download the Setup Script

Download the setup script from the Bigcapital repository: 
curl -o setup.sh https://raw.githubusercontent.com/bigcapitalhq/bigcapital/develop/setup.sh
Make the script executable: 
chmod +x setup.sh

​
Using the Setup Script

Run the setup script interactively: 
./setup.sh
Or pass a specific action directly: 
./setup.sh [action]
Available actions:
ActionDescription
installDownload Docker files and pull images
startStart all Bigcapital services
stopStop all Bigcapital services
restartRestart all Bigcapital services
upgradeUpgrade to the latest version
logsView logs for specific services

​
Interactive Menu

When you run ./setup.sh without arguments, you’ll see an interactive menu: 
--------------------------------------------
         ×      ≠≠≠≠   ____  _                       _ _        _
       ××××   ≠≠≠≠≠    | __ )(_) __ _  ___ __ _ _ __ (_) |_ __ _| |
     ×××××  ≠≠≠≠≠      |  _ \| |/ _` |/ __/ _` | '_ \| | __/ _` | |
   ×××××  ≠≠≠≠≠=       | |_) | | (_| | (_| (_| | |_) | | || (_| | |
 ×××××  ≠≠≠≠≠≠         |____/|_|\__, |\___\__,_| .__/|_|\__\__,_|_|
××××     ≠≠≠                    |___/          |_|
--------------------------------------------
Self-hosted modern core accounting software
--------------------------------------------

Select a Action you want to perform:
   1) Install
   2) Start
   3) Stop
   4) Restart
   5) Upgrade
   6) Logs
   7) Exit

Action [2]:

​
Installation Steps

​
1. Install

Select option 1 or run: 
./setup.sh install
This command will:
  • Clone the latest Docker configuration files from the repository
  • Create an .env file from the example configuration
  • Pull the latest Docker images from GitHub Container Registry
  • Archive any existing configuration files (stored in ./archive/)

​
2. Configure Environment Variables

Before starting the services, edit the .env file to configure your deployment: 
nano .env
Required configurations:
  • Mail settings (MAIL_HOST, MAIL_USERNAME, MAIL_PASSWORD, etc.)
  • JWT_SECRET (generate a strong random value)
  • Database passwords (change default passwords for security)
See the Environment Variables page for detailed information about each variable.

​
3. Start Services

Select option 2 or run: 
./setup.sh start
The script will:
  • Build and start all Docker containers
  • Wait for database migrations to complete
  • Wait for the API server to be ready
  • Display the access URL
Once complete, you’ll see: 
   Database migration completed successfully ✅
   API server started successfully ✅
   Bigcapital server started successfully ✅

   You can access the application at http://localhost
The default access URL is http://localhost:8000 unless you configured a different BASE_URL in the .env file.

​
4. Create Your First Account

Navigate to the displayed URL in your browser and create your first account. No default account is provided.

​
Managing Services

​
Stop Services

./setup.sh stop
Stops all running Docker containers without removing data.

​
Restart Services

./setup.sh restart
Restarts all services. Useful after making changes to environment variables.

​
View Logs

./setup.sh logs
Opens a menu to view logs for specific services:
  1. Webapp
  2. API (Server)
  3. Migration
  4. Envoy Proxy
  5. MariaDB

​
Upgrading Bigcapital

To upgrade to the latest version: 
./setup.sh upgrade
This will:
  1. Stop all running services
  2. Download the latest Docker configuration files
  3. Pull the latest images from the registry
After upgrading, start the services again: 
./setup.sh start

​
What the Script Does

The setup script automates the following components:
Downloads the docker/ directory, docker-compose.prod.yml, and .env.example from the Bigcapital repository. Existing files are archived with timestamps in the ./archive/ directory.
Automatically creates an .env file from .env.example if one doesn’t exist. You’ll need to edit this file to configure mail settings and security credentials.
Detects whether your system uses docker-compose (legacy) or docker compose (plugin) and uses the appropriate command.
During startup, the script monitors the database migration container and waits for migrations to complete before reporting success.
Verifies that the API server starts successfully and listens on the configured port. If migrations fail, the script stops services and displays an error message.

​
Troubleshooting

​
Database Migration Fails

If you see “Bigcapital Server failed to start” during startup:
  1. Check migration logs: ./setup.sh logs → Select option 3
  2. Fix any configuration issues in .env
  3. Stop services: ./setup.sh stop
  4. Start again: ./setup.sh start

​
Port Already in Use

If port 8000 is already in use, edit the .env file and change the PORT variable, or stop the conflicting service.

​
Container Conflicts

If you encounter container name conflicts: 
./setup.sh stop
docker system prune -a
./setup.sh start
docker system prune removes all unused containers and images. Only use this if you’re not running other important Docker containers on the same server.

​
Next Steps

Environment Variables

Learn about all available configuration options

Docker Deployment

Advanced Docker deployment options

Troubleshooting

Common issues and solutions