# PocketBase Local Emulator

Runs a local PocketBase instance in a container for development and testing.

PocketBase v0.36 uses a custom Go-based implementation (`main.go`) extending the 
core framework. The container builds the customized binary on the fly using
`golang:1.24-alpine`.

The Admin UI is available at http://localhost:8090/_/ once the container starts.

---

## Quick start

```
docker build -t hyttahub-pocketbase-emulator -f Podmanfile .
docker run --rm -it \
  -e ALLOW_SELF_JOIN=1 \
  -e ALLOW_ANONYMOUS=1 \
  --name hyttahub-pocketbase-emulator-container \
  -p 8090:8090 \
  -v "$(pwd)/pb_data":/app/pb_data \
  hyttahub-pocketbase-emulator
```

Open the Admin UI at http://localhost:8090/_/ and log in with the default dev credentials created by the migration:

```
Email:    admin@dev.local
Password: Admin1234!
```

> ⚠️ These credentials are for LOCAL DEVELOPMENT ONLY.



---

## What happens on startup

1. **Migrations** (`pb_migrations/`) run automatically at startup via
   PocketBase's built-in migration system:
   - Creates the `users` auth collection (required by `PocketbaseHyttaHubAuth`)
   - Creates the known static tictactoe service collections:
     - `hyttahub/tictactoe/services/status/service_events`
     - `hyttahub/tictactoe/services/status/service_users`
     - `hyttahub/tictactoe/services`

2. **Auto-collection middleware** (`main.go`) registers a global
   Go route interceptor using `app.OnServe().BindFunc()`. Every request to
   `/api/collections/<name>/*` is intercepted before PocketBase resolves
   the collection. If the collection does not exist it is created on the fly
   with the correct field schema for its path suffix:

   | Path suffix          | Fields created                          |
   |----------------------|-----------------------------------------|
   | `**/site_events`     | `p` (text), `v` (number), `t` (text)   |
   | `**/account_events`  | `p` (text), `v` (number), `t` (text)   |
   | `**/service_events`  | `p` (text), `v` (number), `t` (text)   |
   | `**/site_users`      | `u` (number), `t` (text), `m` (text)   |
   | `**/service_users`   | `u` (number), `t` (text), `m` (text)   |
   | anything else        | no fields (open schema)                 |

   This means a developer never has to manually create collections in the
   Admin UI — they appear automatically the first time the app writes to them.

---

## Build

### Podman (ChromeOS / Linux)
```
sudo podman build -t localhost/hyttahub-pocketbase-emulator -f Podmanfile .
```

### Docker (macOS M1/M2 or Linux)
```
docker build -t hyttahub-pocketbase-emulator -f Podmanfile .
```

---

## Run

To enable anonymous users and self-joining (required for the TicTacToe anonymous flow), you should set the `ALLOW_SELF_JOIN` and `ALLOW_ANONYMOUS` environment variables to `1`.

### Configuration Flags

| Flag                | Env Var            | Description                                                                 |
|---------------------|--------------------|-----------------------------------------------------------------------------|
| `--allow-self-join` | `ALLOW_SELF_JOIN`  | Allows authenticated users to see site events and join sites anonymously. |
| `--allow-anonymous` | `ALLOW_ANONYMOUS`  | Enables experimental support for virtual users via the `X-Auth-Email` header.           |

### Podman (ChromeOS / Linux)
```
sudo podman run --rm -it \
  -e ALLOW_SELF_JOIN=1 \
  -e ALLOW_ANONYMOUS=1 \
  --name hyttahub-pocketbase-emulator-container \
  -p 8090:8090 \
  -v "$(pwd)/pb_data":/app/pb_data \
  -v "$(pwd)/pb_public":/app/pb_public \
  localhost/hyttahub-pocketbase-emulator
```

### Docker (macOS M1/M2 or Linux)
```
docker run --rm -it \
  -e ALLOW_SELF_JOIN=1 \
  -e ALLOW_ANONYMOUS=1 \
  --name hyttahub-pocketbase-emulator-container \
  -p 8090:8090 \
  -v "$(pwd)/pb_data":/app/pb_data \
  -v "$(pwd)/pb_public":/app/pb_public \
  hyttahub-pocketbase-emulator
```

---

## Deployment (Hetzner)

To deploy this custom PocketBase emulator to a Hetzner Cloud VPS:

1. **Prerequisites**: Ensure Docker is installed on your Hetzner instance.
2. **Transfer files**: Copy this folder (including `main.go`, `migrations/`, `Podmanfile`, etc.) to your server using `scp` or `git clone`.
3. **Build on server**:
   ```bash
   docker build -t hyttahub-pocketbase -f Podmanfile .
   ```
4. **Run with persistence**:
   Run the container with a restart policy and a persistent volume for the database. Note that we remove `--dev` for production-like environments to ensure more restrictive default behaviors, and we bind to `127.0.0.1:8090` if using a reverse proxy.
   ```bash
   docker run -d \
     --name pocketbase \
     --restart unless-stopped \
     -p 127.0.0.1:8090:8090 \
     -v /var/lib/pocketbase/pb_data:/app/pb_data \
     hyttahub-pocketbase
   ```
5. **SSL & Reverse Proxy**:
   Use **Caddy** or **Nginx** as a reverse proxy to handle SSL (HTTPS). 
   
   **Example Caddyfile**:
   ```caddy
   pb.yourdomain.com {
       reverse_proxy localhost:8090
   }
   ```
   *PocketBase will automatically handle the `X-Forwarded-For` and `X-Real-IP` headers if properly configured in the proxy.*

---

## Admin UI

Open http://localhost:8090/_/ in a browser after starting the container.
On first run you will be prompted to create a superuser account.

---

## Shell into the container

### Podman
```
sudo podman exec -it hyttahub-pocketbase-emulator-container /bin/sh
```

### Docker
```
docker exec -it hyttahub-pocketbase-emulator-container /bin/sh
```

---

## Mounted directories

| Host path (relative to this folder) | Container path       | Purpose |
|--------------------------------------|----------------------|---------|
| `pb_data/`                           | `/app/pb_data`       | SQLite database and PocketBase internal state |
| `pb_public/`                         | `/app/pb_public`     | Static files served at the root URL |

---

## Connecting from the Flutter app

```dart
final pb = PocketBase('http://localhost:8090');
```

Use `http://10.0.2.2:8090` for Android emulator, `http://localhost:8090` for web/desktop/iOS simulator.

---

## Note on PocketBase version

To upgrade the PocketBase version (e.g. from v0.36 to newer), update the `go.mod` file to require the newer version of `github.com/pocketbase/pocketbase` and rebuild.
