> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigcapital.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Script

> Deploy Bigcapital quickly using the automated setup script

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.

<Info>
  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.
</Info>

## 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:

```bash theme={null}
curl -o setup.sh https://raw.githubusercontent.com/bigcapitalhq/bigcapital/develop/setup.sh
```

Make the script executable:

```bash theme={null}
chmod +x setup.sh
```

## Using the Setup Script

Run the setup script interactively:

```bash theme={null}
./setup.sh
```

Or pass a specific action directly:

```bash theme={null}
./setup.sh [action]
```

Available actions:

| Action    | Description                           |
| --------- | ------------------------------------- |
| `install` | Download Docker files and pull images |
| `start`   | Start all Bigcapital services         |
| `stop`    | Stop all Bigcapital services          |
| `restart` | Restart all Bigcapital services       |
| `upgrade` | Upgrade to the latest version         |
| `logs`    | View 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:

```bash theme={null}
./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:

```bash theme={null}
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](/deployment/env_vars) page for detailed information about each variable.

### 3. Start Services

Select option `2` or run:

```bash theme={null}
./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
```

<Info>
  The default access URL is `http://localhost:8000` unless you configured a
  different `BASE_URL` in the `.env` file.
</Info>

### 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

```bash theme={null}
./setup.sh stop
```

Stops all running Docker containers without removing data.

### Restart Services

```bash theme={null}
./setup.sh restart
```

Restarts all services. Useful after making changes to environment variables.

### View Logs

```bash theme={null}
./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:

```bash theme={null}
./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:

```bash theme={null}
./setup.sh start
```

## What the Script Does

The setup script automates the following components:

<AccordionGroup>
  <Accordion icon="download" title="File Management">
    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.
  </Accordion>

  <Accordion icon="file" title="Environment Setup">
    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.
  </Accordion>

  <Accordion icon="server" title="Container Orchestration">
    Detects whether your system uses `docker-compose` (legacy) or
    `docker compose` (plugin) and uses the appropriate command.
  </Accordion>

  <Accordion icon="database" title="Migration Monitoring">
    During startup, the script monitors the database migration container and
    waits for migrations to complete before reporting success.
  </Accordion>

  <Accordion icon="shield-check" title="Health Checks">
    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.
  </Accordion>
</AccordionGroup>

## 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:

```bash theme={null}
./setup.sh stop
docker system prune -a
./setup.sh start
```

<Warning>
  `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.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Environment Variables" icon="sliders" href="/deployment/env_vars">
    Learn about all available configuration options
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/deployment/docker">
    Advanced Docker deployment options
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/deployment/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>