# Local Development Setup

This guide covers setting up the dev environment from scratch after cloning the repo.

---

## First-time setup

`user/plugins/` and `user/data/` are excluded from git but Grav requires them to exist. Create them once:

```bash
mkdir -p user/plugins user/data
```

Then run:

```bash
make setup
```

`make setup` = `build → start → install-plugins → fix-perms`. This builds the Docker image (Grav 2.0 baked in), starts the container, installs all plugins from `plugins.txt`, and fixes file ownership.

The dev server runs at **http://localhost:8081**.

---

## After any docker compose down

Always run `make setup` — not just `make start` — to ensure permissions are correct.

`docker compose restart` (soft restart) preserves the image and is fine for quick restarts. Only `make setup` is needed after `docker compose down`.

---

## Fix 500 errors after plugin install

If the site returns a 500 error after plugin installation or after recreating the container:

```bash
make fix-perms
```

This creates uid 1000 in the container, chowns `/var/www/html` to 1000:1000, and reloads Apache.

---

## Upgrading to a newer Grav RC

Grav 2.0 is baked into the custom Docker image via `Dockerfile`. The base `getgrav/grav` image ships 1.7 — the `Dockerfile` downloads the 2.0 RC bundle from GitHub and overwrites the core files at build time.

To upgrade:
1. Update the bundle URL in `Dockerfile`
2. Run `make setup` — Docker rebuilds the image layer automatically

---

## Required system.yaml settings (Grav 2.0)

After upgrading, verify these are set in `user/config/system.yaml`:

```yaml
accounts:
  type: flex      # required for Admin2 API
pages:
  type: flex      # required for Admin2 pages API
```

---

## Admin user API permissions

The admin user account needs `api.*` permissions for Admin2. In `user/accounts/<username>.yaml`:

```yaml
access:
  admin:
    login: true
    super: true
  api:
    super: true
    access: true
```

---

## Disable the old admin plugin

Both `admin` and `admin2` route to `/admin` and conflict. After installing `admin2`, disable the old one:

In `user/plugins/admin/admin.yaml`:
```yaml
enabled: false
```

---

## JWT secret

Leave `jwt_secret: ''` in `user/plugins/api/api.yaml`. It works for local dev; production installs generate a secure secret automatically during `make remote-install`.

---

## Language URL prefix

If Grav redirects to `/en/...` URLs, ensure `user/config/system.yaml` contains:

```yaml
languages:
  supported: [en]
  include_default_lang: false
```

Without `include_default_lang: false`, Grav adds a language prefix to all URLs even for single-language sites.