> ## Documentation Index
> Fetch the complete documentation index at: https://swiftchats-documentation.axis96.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Guide

<Info>
  Before beginning the installation, make sure your environment meets [System requirements](/get-started/system-requirements).
</Info>

<Warning>
  ### Important Info From v2.4

  * Ensure that you are using php v8.2
  * Ensure that you have enabled `imagick` extension in your server (If not you might experience error 500).
  * Ensure that you are running either `MYSQL > 5.7.7` or `MariaDB > 10.2.2` (Alternatively, you may enable the innodb\_large\_prefix option for your database)
</Warning>

## 1. Obtain the package

After purchasing Swiftchats, you will get a zipped folder. After unzipping the folder, you will get three folders, the source code folder, update folder and the documentation folder.

> Documentation <br />
> Source-code <br />
> Update

## 2. Database setup (MySQL)

1. Create a new MySQL database.
2. Create a new MySQL username and password.
3. Assign full privileges to your database username.

<Tip>
  On a **VPS**, create the database with the MySQL or MariaDB client (`mysql` / `mariadb`), or run the equivalent SQL from an admin tool. Grant the application user full privileges on that database and allow connections from the host where PHP runs (often `localhost`).
</Tip>

## 3. Uploading code

<Info>
  Before starting to upload the files, please make sure your file explorer has the option to view hidden files turned on. On some operating systems, the dotfiles are hidden by default.
</Info>

<Tip>
  **Ubuntu and similar VPS or dedicated servers:** The most reliable approach is to push your project to a **private GitHub repository** (or another Git host), then **clone** or **pull** the code on the server with Git. That gives you version history, simpler updates, and avoids incomplete SFTP uploads or missing application files. Create environment files such as **`.env`** directly on the server (never commit secrets to Git).
</Tip>

* **Git (recommended on Linux servers):** Create a private repository, add the Swiftchats source code (including dotfiles your workflow requires), deploy keys or SSH access on the server, then `git clone` into your web root or project directory (for example `/var/www/your-site`).
* **Manual upload (alternative):** Copy the source-code folder to your project directory on the server (for example under `/var/www/`) using **SFTP** or **rsync**. Ensure hidden files are included.
* Ensure you have already created the MySQL database and DB user on the server and assigned that user to the database (see section 2).

## 4. Installer setup

Once you have configured the steps above, go to your domain or subdomain which should redirect you to the installation page. Go through each installation step and grant folder permissions where necessary.

## 5. Evolution API on Ubuntu (Docker)

The **WhatsApp QR connect** add-on uses [Evolution API](https://github.com/EvolutionAPI/evolution-api) as the WhatsApp Web gateway. On Ubuntu, the recommended approach is to run Evolution API with Docker and Docker Compose alongside your Swiftchats stack.

<Warning>
  **WhatsApp QR connect add-on required.** The Swiftchats WhatsApp QR connect integration (settings, connectivity, and related features) is only available if you have **purchased the WhatsApp QR connect add-on** for your Swiftchats license. Complete the add-on purchase before relying on this stack in production.
</Warning>

<Steps>
  <Step title="Install Docker Engine and Compose" titleSize="p">
    On Ubuntu 20.04 or 22.04 LTS:

    ```bash theme={null}
    sudo apt update
    sudo apt install -y ca-certificates curl gnupg
    sudo install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
    sudo chmod a+r /etc/apt/keyrings/docker.gpg
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
    sudo apt update
    sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    sudo usermod -aG docker "$USER"
    ```

    Log out and back in (or open a new SSH session) so the `docker` group applies. Verify:

    ```bash theme={null}
    docker --version
    docker compose version
    ```
  </Step>

  <Step title="Create the Evolution API project directory" titleSize="p">
    Create the project under **`/opt/evolution-api`** (default path used by Evolution API):

    ```bash theme={null}
    sudo mkdir -p /opt/evolution-api
    sudo chown "$USER":"$USER" /opt/evolution-api
    cd /opt/evolution-api
    ```

    The next steps assume your shell is inside **`/opt/evolution-api`**.
  </Step>

  <Step title="Configure environment variables" titleSize="p">
    Create or edit **`.env`** in **`/opt/evolution-api`**:

    ```bash theme={null}
    nano .env
    ```

    Paste these variables into your `.env` file:

    ```dotenv theme={null}
    DATABASE_ENABLED=true
    DATABASE_PROVIDER=postgresql
    DATABASE_CONNECTION_URI=postgresql://postgres:postgres@postgres:5432/evolution?schema=public
    DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange

    AUTHENTICATION_API_KEY=your-authentication-api-key
    WA_BUSINESS_TOKEN_WEBHOOK=your-whatsapp-business-token-webhook

    DATABASE_SAVE_DATA_INSTANCE=true
    DATABASE_SAVE_DATA_NEW_MESSAGE=true
    DATABASE_SAVE_MESSAGE_UPDATE=true
    DATABASE_SAVE_DATA_CONTACTS=true
    DATABASE_SAVE_DATA_CHATS=true
    DATABASE_SAVE_DATA_LABELS=true
    DATABASE_SAVE_DATA_HISTORIC=true
    CONFIG_SESSION_PHONE_VERSION=2.3000.1029992881

    CACHE_REDIS_ENABLED=true
    DATABASE_PROVIDER=postgresql
    CACHE_REDIS_URI=redis://redis:6379/6
    CACHE_REDIS_PREFIX_KEY=evolution
    CACHE_REDIS_SAVE_INSTANCES=false
    CACHE_LOCAL_ENABLED=false
    ```

    Replace **`your-authentication-api-key`** and **`your-whatsapp-business-token-webhook`** with real secrets (for example strong random values from [generate-random.org API keys](https://generate-random.org/api-keys)).

    <Note>
      Save **`AUTHENTICATION_API_KEY`** somewhere secure after you set it. Later, set **`EVOLUTION_API_KEY`** in the Swiftchats **`.env`** to the **same value** (see **Connect Swiftchats to the WhatsApp gateway** at the end of this section).
    </Note>
  </Step>

  <Step title="Create YAML file for Docker" titleSize="p">
    In **`/opt/evolution-api`** (same directory as **`.env`**), create **`docker-compose.yaml`**:

    ```bash theme={null}
    nano docker-compose.yaml
    ```

    Paste this into the file:

    ```yaml theme={null}
    services:

      postgres:
        container_name: evolution_postgres
        image: postgres:15
        restart: always
        networks:
          - evolution-net
        command: ["postgres", "-c", "max_connections=1000"]
        ports:
          - "127.0.0.1:5432:5432"
        environment:
          - POSTGRES_PASSWORD=postgres
          - POSTGRES_USER=postgres
          - POSTGRES_DB=evolution
        volumes:
          - postgres_data:/var/lib/postgresql/data

      redis:
        image: redis:latest
        container_name: evolution_redis
        restart: always
        networks:
          - evolution-net
        command: redis-server --port 6379 --appendonly yes
        ports:
          - "127.0.0.1:6379:6379"
        volumes:
          - evolution_redis:/data

      evolution-api:
        container_name: evolution_api
        image: evoapicloud/evolution-api:latest
        restart: always
        depends_on:
          - redis
          - postgres
        ports:
          - "127.0.0.1:8080:8080"
        volumes:
          - evolution_instances:/evolution/instances
        networks:
          - evolution-net
        env_file:
          - .env

    volumes:
      postgres_data:
      evolution_redis:
      evolution_instances:

    networks:
      evolution-net:
        driver: bridge
    ```

    Save and exit the editor.
  </Step>

  <Step title="Start the services" titleSize="p">
    From **`/opt/evolution-api`**, launch Evolution API with Docker Compose:

    ```bash theme={null}
    docker compose up -d
    ```

    This starts:

    * **Evolution API** (port **8080**)
    * **PostgreSQL** (port **5432** on localhost)
    * **Redis** (port **6379** on localhost)

    Verify the services are running:

    ```bash theme={null}
    docker compose ps
    ```
  </Step>

  <Step title="Reverse proxy (Nginx)" titleSize="p">
    Create a reverse proxy to expose the API safely.

    ```bash theme={null}
    sudo nano /etc/nginx/sites-available/evolution
    ```

    Paste this:

    ```nginx theme={null}
    server {
        server_name evolution.yourdomain.com; #Replace with your subdomain
        client_max_body_size 10M;
        location / {
            proxy_pass http://127.0.0.1:8080;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;

            # Headers for API & Webhooks
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
    ```

    Enable the site and reload Nginx:

    ```bash theme={null}
    sudo ln -s /etc/nginx/sites-available/evolution /etc/nginx/sites-enabled/
    sudo nginx -t
    sudo systemctl restart nginx
    sudo certbot --nginx -d evolution.yourdomain.com
    ```

    Replace **`evolution.yourdomain.com`** with the same hostname you set in Nginx **`server_name`**. For more options or troubleshooting, see [How to install in Nginx](/get-started/common-issues#how-to-install-in-nginx).
  </Step>

  <Step title="Connect Swiftchats to the WhatsApp gateway" titleSize="p">
    In the Swiftchats **`.env`** file on the server, set:

    * **`EVOLUTION_BASE_URL`** — Same base URL as **`SERVER_URL`** in the Evolution API gateway (for example `https://evolution.yourdomain.com`).
    * **`EVOLUTION_API_KEY`** — Must match **`AUTHENTICATION_API_KEY`** from the gateway’s **`.env`** (use the value you saved when configuring Evolution API).

    Clear config cache after editing:

    ```bash theme={null}
    php artisan config:clear
    ```

    <Note>
      For the latest Evolution API options, environment variables, and troubleshooting, see the [Evolution API installation documentation](https://mintlify.wiki/EvolutionAPI/evolution-api/installation).
    </Note>
  </Step>
</Steps>

## 6. Laravel jobs and queues

To ensure successful delivery of WhatsApp campaigns, it's essential to set up a queue system that runs at scheduled intervals to dispatch campaigns efficiently. On a VPS, use **Supervisor** to run Laravel queue workers and a **cron** entry for Laravel's scheduler (see step 6 below).

<Warning>
  Supervisor requires shell access (SSH) and permission to install system packages (for example `sudo` on Ubuntu).
</Warning>

If you decide to use Laravel queues, go to your `.env` file and change the following:

```dotenv theme={null}
QUEUE_CONNECTION=database
QUEUE_MEMORY=128
QUEUE_TIMEOUT=300
QUEUE_DRIVER=database
```

<Steps>
  <Step title="Install Supervisor" titleSize="p">
    On Ubuntu or Debian:

    ```bash theme={null}
    sudo apt update && sudo apt install supervisor -y
    ```

    After installation, start Supervisor and enable it to run on boot:

    ```bash theme={null}
    sudo systemctl enable --now supervisor
    ```
  </Step>

  <Step title="Create a Supervisor configuration file for Laravel queues" titleSize="p">
    Create a new configuration file inside `/etc/supervisor/conf.d/`:

    ```bash theme={null}
    sudo nano /etc/supervisor/conf.d/laravel-queue.conf
    ```

    Add the following content:

    ```ini theme={null}
    [program:laravel-queue]
    process_name=%(program_name)s_%(process_num)02d
    command=php /path-to-your-project/artisan queue:work --queue=default,campaign-logs,campaign-messages --tries=3 --timeout=3600
    autorestart=true
    numprocs=1
    redirect_stderr=true
    stdout_logfile=/var/log/laravel-queue.log
    ```

    Replace `/path-to-your-project/` with your actual Laravel project path.
  </Step>

  <Step title="Apply Supervisor changes" titleSize="p">
    After creating the configuration file, run the following commands to update and start Supervisor:

    ```bash theme={null}
    sudo supervisorctl reread
    sudo supervisorctl update
    sudo supervisorctl start laravel-queue:*
    ```

    To check if Supervisor is running correctly, use:

    ```bash theme={null}
    sudo supervisorctl status
    ```
  </Step>

  <Step title="Monitoring and logs" titleSize="p">
    You can check the logs if anything goes wrong:

    ```bash theme={null}
    tail -f /var/log/laravel-queue.log
    ```

    If the queue worker stops unexpectedly, restart Supervisor:

    ```bash theme={null}
    sudo supervisorctl restart laravel-queue
    ```
  </Step>

  <Step title="Ensure Supervisor starts on boot" titleSize="p">
    To prevent queue workers from stopping after a reboot, enable Supervisor:

    ```bash theme={null}
    sudo systemctl enable supervisor
    ```
  </Step>

  <Step title="Add a cron job for the Laravel scheduler" titleSize="p">
    Edit the crontab:

    ```bash theme={null}
    crontab -e
    ```

    Add this line (runs Laravel's scheduler every minute):

    ```text theme={null}
    * * * * * cd /path-to-your-project && /usr/bin/php artisan schedule:run >> /dev/null 2>&1
    ```

    Replace `/path-to-your-project/` with your actual Laravel project path.
  </Step>
</Steps>

## 7. Trouble-shooting your installation

If you are facing issues with the installer, try the following:

**Grant access to your `.env` file** — from your project directory, run:

```bash theme={null}
chown -R www-data:www-data .env
```

**Clear the installer lock** — open the `storage` folder and delete the `installed` file.

**Retry** the installation in your browser.