Development Setup

Prerequisites

Elixir 1.17+
Erlang/OTP 26+
PostgreSQL 16+ with PostGIS extension
Node.js 20+ (for asset compilation)

Quick Start

# 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:

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:

Installs Hex and Rebar dependencies
Fetches Elixir dependencies
Creates the development database
Runs migrations
Seeds device data

Manual Database Setup

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

# 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

# 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:

# 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 for coding conventions, and Architecture Overview for system design.

2.7 KiB Raw Blame History