yakpanel-core/docs/ubuntu-dev-install.md

# YakPanel Ubuntu Dev Install

This setup brings up the YakPanel 2026 stack on Ubuntu 22.04/24.04.

## Clone the repository

```bash
git clone https://source.yakpanel.com/admin/yakpanel-core.git
cd yakpanel-core
```

## Quick install

```bash
cd /path/to/yakpanel-core
chmod +x scripts/install-ubuntu.sh scripts/bootstrap-dev.sh
./scripts/install-ubuntu.sh
```

## One-click install

```bash
cd /path/to/yakpanel-core
chmod +x one-click-installer.sh
./one-click-installer.sh
```

## Start/stop commands

```bash
make init
make up
make migrate
make ps
make logs
make down
```

## Services
Host ports are defined in `.env` (see `.env.example`). Defaults avoid common conflicts:

- **Web control panel (full UI):** `http://localhost:3080/` (`PANEL_UI_PORT`) <20> default login `admin` / `admin` (change immediately). API is proxied at `/api`.
- Laravel scaffold API health: `http://localhost:18080/health` (`API_PORT`)
- PostgreSQL: `localhost:15432` (`POSTGRES_PORT`)
- Redis: `localhost:16379` (`REDIS_PORT`)
- NATS monitor: `http://localhost:18222` (`NATS_MONITOR_PORT`)
- MinIO console: `http://localhost:19001` (`MINIO_CONSOLE_PORT`)
- Prometheus: `http://localhost:19090` (`PROMETHEUS_PORT`)
- Grafana: `http://localhost:13000` (`GRAFANA_PORT`)

First boot builds Docker images for `YakPanel-server` (backend + frontend); this can take several minutes.

## Troubleshooting

### `permission denied while trying to connect to the docker API`

After adding your user to the `docker` group, your **current** shell may not see that group until you log out and back in. Install scripts use `scripts/docker-compose.sh`, which runs Compose via `sg docker` when needed so the first run succeeds without a re-login.

If you still see the error, run:

```bash
newgrp docker
```

or log out and SSH in again, then:

```bash
bash scripts/docker-compose.sh up -d --build
```

### `failed to bind host port ... address already in use`

Another service on the host is using the same published port. Run:

```bash
bash scripts/ensure-env-ports.sh
bash scripts/docker-compose.sh down
bash scripts/docker-compose.sh up -d --build
```

Or edit `.env` manually (raise `REDIS_PORT`, `POSTGRES_PORT`, etc.).

## Notes
- This is a development-first integrated stack with a real control panel UI and supporting services.
- Database schema is automatically applied by `db-migrate` during bootstrap and can be re-run with `make migrate`.