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

# Installation

> Install the LaraOwl server with Docker or Composer.

There are two supported ways to run the LaraOwl server. Choose the one that fits your infrastructure.

<CardGroup cols={2}>
  <Card title="Docker" icon="docker" href="#docker">
    The fastest path to production. Ships PHP, PostgreSQL, Redis, Reverb, and automatic SSL.
  </Card>

  <Card title="Composer" icon="php" href="#composer">
    Full control on your own PHP/database stack. You manage the supporting services.
  </Card>
</CardGroup>

<Note>
  Before you begin, confirm your environment meets the [server requirements](/server-requirements).
</Note>

## Docker

The repository includes a production-ready `docker/Dockerfile` and `docker-compose.yaml`. The Compose stack runs every service LaraOwl needs: the web app, a Horizon queue worker, a schedule worker, the Reverb WebSocket server, PostgreSQL, Redis, and a Caddy reverse proxy that provisions and renews SSL certificates automatically.

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/laraowl/laraowl.git
    cd laraowl
    ```
  </Step>

  <Step title="Create the environment file">
    Copy the production template and edit it:

    ```bash theme={null}
    cp .env.prod .env
    ```

    Update at least the following values in `.env`:

    ```dotenv theme={null}
    APP_URL=https://your-production-domain.com
    APP_HOSTNAME=your-production-domain.com

    # Generate a random 6-digit ID and 20-character key/secret
    REVERB_APP_ID=000000
    REVERB_APP_KEY=xxxxxxxxxxxxxxxxxxxxx
    REVERB_APP_SECRET=xxxxxxxxxxxxxxxxxxxxx

    # Change the default database and Redis passwords
    DB_PASSWORD=your-secure-password
    REDIS_PASSWORD=your-secure-password
    ```

    <Info>
      The Compose file already wires the internal service hostnames (`db`, `redis`, `reverb`). You only need to change these if you customize the stack.
    </Info>
  </Step>

  <Step title="Point your DNS">
    LaraOwl serves the dashboard and the WebSocket endpoint on separate hostnames. Create DNS `A` records for **both**:

    * `your-production-domain.com` — the dashboard
    * `ws.your-production-domain.com` — the Reverb WebSocket server

    Caddy fetches and renews SSL certificates for both automatically.
  </Step>

  <Step title="Build and start the stack">
    ```bash theme={null}
    docker compose up -d --build
    ```

    The application key is generated and migrations run on first boot. Your server will be available at `https://your-production-domain.com`.
  </Step>

  <Step title="Create the first admin user">
    Registration is disabled by default. Open a shell in the app container and create an admin account via Tinker:

    ```bash theme={null}
    docker compose exec -ti app /bin/bash
    php artisan tinker
    ```

    ```php theme={null}
    App\Models\User::updateOrCreate(
        ['email' => 'admin@laraowl.com'],
        ['name' => 'Admin', 'password' => bcrypt('changeme')]
    );
    ```

    <Warning>
      Change the password immediately after your first login.
    </Warning>
  </Step>
</Steps>

## Composer

Install LaraOwl directly onto your own PHP and database stack. With this method you are responsible for running the queue worker, Reverb, and the scheduler yourself.

<Steps>
  <Step title="Create the project">
    ```bash theme={null}
    composer create-project laraowl/laraowl laraowl
    cd laraowl
    ```
  </Step>

  <Step title="Install frontend dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Set up the environment">
    ```bash theme={null}
    cp .env.example .env
    php artisan key:generate
    ```

    Configure your database connection in `.env`. See [Configuration](/configuration) for the full list of variables.
  </Step>

  <Step title="Run migrations">
    ```bash theme={null}
    php artisan migrate
    ```
  </Step>

  <Step title="Build frontend assets">
    ```bash theme={null}
    npm run build
    ```
  </Step>

  <Step title="Serve the application">
    ```bash theme={null}
    php artisan serve
    ```
  </Step>
</Steps>

### Required background processes

LaraOwl needs these processes running alongside the web server. In production, manage them with a supervisor such as [Supervisor](#supervisor-example) rather than running them manually.

```bash theme={null}
# Process queued telemetry records (required)
php artisan queue:work

# WebSocket server for real-time updates (required)
php artisan reverb:start

# Scheduler for uptime checks & data pruning (required)
php artisan schedule:work
```

<Tip>
  LaraOwl ships with **Laravel Horizon**. If you use Redis for your queue, run `php artisan horizon` instead of `queue:work` to get a managed worker pool and the Horizon dashboard.
</Tip>

### Scheduler cron entry

For production, register Laravel's scheduler with cron instead of running `schedule:work`:

```cron theme={null}
* * * * * cd /path/to/laraowl && php artisan schedule:run >> /dev/null 2>&1
```

This drives uptime checks (every 30 seconds) and the daily data-pruning job.

### Supervisor example

An example Supervisor configuration for the queue worker and Reverb:

```ini theme={null}
[program:laraowl-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/laraowl/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/laraowl/queue.log

[program:laraowl-reverb]
command=php /path/to/laraowl/artisan reverb:start
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/laraowl/reverb.log
```

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    Fine-tune your environment variables and services.
  </Card>

  <Card title="Getting started" icon="rocket" href="/quickstart">
    Create your first project and connect an application.
  </Card>
</CardGroup>