# Configuration

Source: https://laraport.app/docs/configuration/

> laraport keeps its settings in one YAML file: where it lives, a full example, every global setting and your custom commands.

laraport keeps its configuration in one YAML file:

```
~/.config/laraport/config.yaml
```

Use another file with an argument or an environment variable:

```bash
laraport /path/to/config.yaml
LARAPORT_CONFIG=/path/to/config.yaml laraport
```

`LARAPORT_NO_UPDATE_CHECK=1` turns off the [check for new versions](#checking-for-new-versions), like `no_update_check`.

You rarely need to edit it by hand. Servers are added and edited from the server list (`a`, `e`, `d`) or imported from `~/.ssh/config` (`i`), settings from `s`, and containers from `e` on the container list.

## Editing from the UI

- Saving rewrites the whole file. Comments and formatting are not kept, so the first time laraport writes it, the original is kept as `config.yaml.bak`.
- The file is written atomically with mode `0600`.
- Without a config only the implicit **Local** server is shown. Once you add a server, Local is written too, so it stays. Delete it if you don't want it.

## Full example

```yaml
settings:                       # all optional
  downloads_dir: "~/Downloads"  # where dumps and archives are saved
  host_key_check: accept-new    # or: strict
  wrap_logs: false              # start log screens with line wrapping
  hide_stopped: false           # list running containers only
  usage_columns: auto           # CPU/MEM columns: auto | always | never
  server_panel: full            # above the container list: full | compact | off
  check_servers_on_start: false # check every server when laraport starts
  allow_restore: false          # offer restoring dumps into databases
  no_update_check: false        # do not ask GitHub for a newer release
  stats_interval: 2             # Stats refresh, seconds (1–60)
  no_sql_history: false         # do not keep the history (SQL, Tinker, commands)
  sql_history_size: 200         # entries kept per database or container

commands:                       # command groups shown for every container
  - name: "Cache"
    commands:
      - label: "cache:clear"
        cmd: "php artisan cache:clear"
        desc: "Flush the application cache"

servers:
  - name: "Production"
    type: ssh
    host: "your-server.com"
    port: 22
    user: "root"
    key: "~/.ssh/id_ed25519"
    jump_host: "ops@bastion.example.com:2222"  # optional
    docker_cmd: "sudo -n docker"                # optional
    root_path: "/var/www/html"                  # optional
    read_only: true                             # optional: refuse every change
    containers:
      - service: "swarm/myapp_web"
        display_name: "Web"
        favorite: true
      - name: "myapp-*"
        display_name: "My App"
        custom_logs:
          - /var/log/nginx/error.log

  - name: "Local Dev"
    type: local
```

Servers are described in [Servers and SSH](https://laraport.app/docs/servers/), container entries in [Container settings](https://laraport.app/docs/container-settings/).

## Settings

Press `s` on the server list to change these.

| Setting | Default | Description |
|---|---|---|
| `downloads_dir` | `~/Downloads` | Where dumps, archives and exports are saved |
| `host_key_check` | `accept-new` | `strict` refuses servers that are not already in `~/.ssh/known_hosts` |
| `wrap_logs` | `false` | Start log and output screens with line wrapping (`f2` toggles it) |
| `hide_stopped` | `false` | List running containers only |
| `usage_columns` | `auto` | CPU and MEM columns in the container list: `auto` shows them from 120 columns wide, `always`, or `never` (which also skips the `docker stats` query) |
| `server_panel` | `full` | The server panel above the container list: `full`, `compact` (one line) or `off` (the server is not queried). `p` in the list switches full and compact and saves the choice |
| `check_servers_on_start` | `false` | **Check servers on start**: check every server when laraport starts and show its state on the home screen. `c` does it any time. See [Checking every server](https://laraport.app/docs/servers/#checking-every-server) |
| `allow_restore` | `false` | **Allow restoring dumps**: offer Restore a dump in a database's actions. Each restore still asks for the database's name. See [Restoring a dump](https://laraport.app/docs/databases/#restoring-a-dump) |
| `no_update_check` | `false` | Turns off **Check for new versions**. See [Checking for new versions](#checking-for-new-versions) |
| `stats_interval` | `2` | Seconds between Stats samples (1–60) |
| `no_sql_history` | `false` | Turns off **Save history**: do not keep the history of SQL queries, Tinker code and Artisan, Composer and npm commands. **Clear history** in Settings deletes it |
| `sql_history_size` | `200` | **History size**: entries kept per database, and per container for Tinker and commands |

## Custom commands

`commands` defines groups of shell commands that appear under **Commands** on the Laravel tab. Global groups are shown for every container; a container entry can add its own, which come first.

```yaml
commands:
  - name: "Deploy"
    commands:
      - label: "optimize"
        cmd: "php artisan optimize"
        desc: "Cache config, routes and views"
```

## Checking for new versions

Once a day laraport asks GitHub for its latest release. When it is newer than yours, the home screen says so, with how to upgrade: `brew upgrade laraport` for a Homebrew install, the releases page otherwise.

- The request is one GET to the GitHub API with `laraport/<version>` as the user agent. Nothing about you or your servers is sent.
- The answer is kept for a day in `~/.config/laraport/update.json`.
- Development builds never ask, and prereleases are not offered.
- A failed check stays silent.

Switch off **Check for new versions** in Settings (`no_update_check: true`), or set `LARAPORT_NO_UPDATE_CHECK=1`, and laraport makes no request at all.

## Other files

Besides `config.yaml`, laraport keeps these in `~/.config/laraport/`, all on your computer only:

| File | Holds |
|---|---|
| `config.yaml.bak` | The original config, kept the first time laraport rewrites it |
| `history.json` | The history of SQL queries, Tinker code and Artisan, Composer and npm commands, mode `0600`. Off with `no_sql_history`. Before 0.3.3 it was `sql_history.json`, which is moved on first use |
| `journal.jsonl` | The [journal](https://laraport.app/docs/journal/) of every change, mode `0600` |
| `recent.json` | The containers you opened lately, for [`ctrl+p`](https://laraport.app/docs/interface/#jump-to-a-container), mode `0600`, 20 at most |
| `update.json` | The last answer of the version check |