Everything you need to go from zero to a fully running Pinpoint 311 deployment, step by step.
| Requirement | How to get it |
|---|---|
| Server or VM | Any cloud provider or on-premise. Min: 1 vCPU, 1 GB RAM. |
| Docker & Compose | Install Docker → |
| Git | Pre-installed on most servers. If not: sudo apt install git |
| Requirement | Why |
|---|---|
| Google Cloud | Maps, Vertex AI (Gemini), Translate, Secret Manager |
| Auth0 Account | Staff SSO, MFA, passkeys — free tier |
| Custom Domain | e.g. 311.yourtown.gov |
| SMTP Server | Confirmation & status emails |
Open a terminal on your server:
That's it — the entire codebase is on your server.
| Variable | What to set |
|---|---|
DOMAIN |
Your domain, or localhost for testing |
DB_PASSWORD |
A strong, unique database password |
SECRET_KEY |
Generate with the command below |
ADMIN_EMAIL |
Your admin contact email |
Generate your SECRET_KEY:
You should see backend, frontend, db,
redis, caddy, celery_worker, and
celery_beat — all Up.
| Portal | URL |
|---|---|
| Resident Portal | http://localhost/ |
| Staff Dashboard | http://localhost/staff |
| Admin Console | http://localhost/admin |
| Research Lab | http://localhost/research |
| API Docs | http://localhost/api/docs |
Click the returned magic link — it logs you into the Admin Console with full privileges.
| Setting | Value |
|---|---|
| Callback URLs | https://311.yourtown.gov/api/auth/callback |
| Logout URLs | https://311.yourtown.gov/staff |
| Web Origins | https://311.yourtown.gov |
Go to Setup & Integration, enter your Auth0 Domain, Client ID, and Client Secret.
Enter the key in Admin Console → Setup & Integration → Google Maps.
In Google Cloud Console, enable Vertex AI API and Cloud Translation API.
Upload in Admin Console → Setup & Integration → Google Cloud. The key is encrypted with AES-128-CBC.
In Admin Console → Setup & Integration:
| Field | Example |
|---|---|
| SMTP Host | smtp.gmail.com |
| SMTP Port | 587 (TLS) |
| Username | 311@yourtown.gov |
| From Address | 311@yourtown.gov |
Requests outside the boundary are automatically rejected. Get your file from:
Upload in Setup & Integration → Municipality Boundaries.
In Admin Console → Services, create categories (Pothole, Streetlight, etc.):
| Setting | Description |
|---|---|
| Routing | Township Handled, Third-Party, or Road-Based |
| Department | Which team handles it |
| Questions | Follow-up questions per service |
In Admin Console → Branding:
Auto-applied to Resident Portal, all emails, SMS, and Staff Dashboard.
In Branding → Legal Documents:
All support Markdown formatting. Sensible defaults included.
| Type | Name | Value |
|---|---|---|
| A | 311.yourtown.gov |
Your server IP |
Caddy auto-provisions SSL and redirects HTTP → HTTPS.
GCP_SERVICE_ACCOUNT_JSON, GOOGLE_CLOUD_PROJECT) stay in
the
local DB — they're needed to access Secret Manager itself.In Staff Management:
| Role | Access |
|---|---|
| Staff | View, manage, resolve requests |
| Admin | Full Admin Console access |
| Researcher | Privacy-preserved analytics |
Staff log in via Auth0 SSO — no passwords needed.
| ✓ | Item |
|---|---|
| ☐ | Secure DB_PASSWORD and SECRET_KEY (not defaults) |
| ☐ | Auth0 configured, bootstrap disabled |
| ☐ | Google Maps key working |
| ☐ | Municipality boundary uploaded |
| ☐ | At least one service category |
| ☐ | At least one department with staff |
| ☐ | SMTP email configured and tested |
| ☐ | Branding set (logo, name, colors) |
| ☐ | Legal documents reviewed |
| ☐ | Custom domain with HTTPS |
| ☐ | Full lifecycle test: submit → staff → resolve → email |
| State | Period |
|---|---|
| Texas | 10 years |
| NJ, PA, WI | 7 years |
| NY, MI, WA, CT | 6 years |
| CA, FL, most | 5 years (default) |
| GA, MA | 3 years |
Need help? We're here for you.
© 2024–2026 Pinpoint 311 · MIT License · Fiscally sponsored by Hack Club 501(c)(3)