129 lines
2.7 KiB
Markdown
129 lines
2.7 KiB
Markdown
# Development Setup
|
|
|
|
## Prerequisites
|
|
|
|
- Elixir 1.17+
|
|
- Erlang/OTP 26+
|
|
- PostgreSQL 16+ with PostGIS extension
|
|
- Node.js 20+ (for asset compilation)
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone and cd
|
|
git clone <repo-url>
|
|
cd aprs.me
|
|
|
|
# Install dependencies and set up database
|
|
mix setup
|
|
|
|
# Start dev server
|
|
mix phx.server
|
|
# or with IEx:
|
|
iex -S mix phx.server
|
|
```
|
|
|
|
The application will be available at `http://localhost:4000`.
|
|
|
|
## Nix Development Environment (Optional)
|
|
|
|
A reproducible development environment is available via Nix:
|
|
|
|
```bash
|
|
nix develop
|
|
# or with direnv:
|
|
direnv allow
|
|
```
|
|
|
|
This provides all required tooling (Elixir, Erlang, PostgreSQL, Node.js) without manual installation.
|
|
|
|
## Database Setup
|
|
|
|
The `mix setup` command:
|
|
1. Installs Hex and Rebar dependencies
|
|
2. Fetches Elixir dependencies
|
|
3. Creates the development database
|
|
4. Runs migrations
|
|
5. Seeds device data
|
|
|
|
### Manual Database Setup
|
|
|
|
```bash
|
|
mix ecto.create
|
|
mix ecto.migrate
|
|
mix run priv/repo/seeds.exs
|
|
```
|
|
|
|
**Important:** PostGIS extension must be enabled on the database. The migration pipeline handles this, but ensure your PostgreSQL installation includes PostGIS.
|
|
|
|
## Running Tests
|
|
|
|
```bash
|
|
# Full test suite
|
|
mix test
|
|
|
|
# Watch mode (auto-rerun on changes)
|
|
mix test.watch
|
|
|
|
# Coverage report
|
|
mix coveralls.html
|
|
# View at cover/excoveralls.html
|
|
```
|
|
|
|
## Code Quality
|
|
|
|
```bash
|
|
# Format code
|
|
mix format
|
|
|
|
# Static analysis
|
|
mix credo --strict
|
|
|
|
# Type checking
|
|
mix dialyzer
|
|
|
|
# Security scan
|
|
mix sobelow
|
|
```
|
|
|
|
## Asset Compilation
|
|
|
|
Frontend assets use ESBuild + Tailwind CSS v4:
|
|
|
|
```bash
|
|
# Development (watch mode)
|
|
mix assets.build
|
|
|
|
# Production
|
|
MIX_ENV=prod mix assets.deploy
|
|
```
|
|
|
|
JavaScript entry points are in `assets/js/`:
|
|
- `app.ts` — Core application (always loaded)
|
|
- `map.ts` — Map functionality (lazy-loaded)
|
|
- `map_helpers.ts` — Leaflet utilities
|
|
- `map_fixes.ts` — Leaflet bug workarounds
|
|
|
|
CSS: Tailwind v4 in `assets/css/app.css` with custom dark mode and Leaflet overrides.
|
|
|
|
## Useful Commands
|
|
|
|
| Command | Purpose |
|
|
|---|---|
|
|
| `mix phx.server` | Start dev server |
|
|
| `iex -S mix phx.server` | Start with interactive shell |
|
|
| `mix test` | Run test suite |
|
|
| `mix test.watch` | Auto-rerun tests on changes |
|
|
| `mix format` | Format Elixir code |
|
|
| `mix credo --strict` | Lint check |
|
|
| `mix dialyzer` | Type checking |
|
|
| `mix sobelow` | Security scan |
|
|
| `mix coveralls.html` | Test coverage report |
|
|
| `mix phx.routes` | List all routes |
|
|
| `mix ecto.migrate` | Run pending migrations |
|
|
| `mix ecto.rollback` | Rollback last migration |
|
|
| `mix parse_file <path>` | Parse raw APRS log file |
|
|
|
|
## Project Structure
|
|
|
|
See [AGENTS.md](../../AGENTS.md) for coding conventions, and [Architecture Overview](../architecture/overview.md) for system design.
|