README

Open-Source Civic Issue Tracking and Open311 Platform for Drupal 11

Key Features

Citizen Engagement:
An intuitive interface lets citizens report issues easily—complete with photos, detailed descriptions, and geolocation data—to ensure that community problems are visible and actionable.
Nuxt.js Decoupled Frontend:
A dynamic frontend, built with Nuxt.js, offers a sleek, responsive, and engaging user experience. It seamlessly complements the Drupal administration backend, creating an integrated platform designed for modern civic engagement.
Advanced Mapping & Geolocation:
Interactive maps allow users to pinpoint exact problem locations, making it easier for public authorities to identify and respond to issues efficiently.
Open311 Compliant API:
The platform offers a standardized GeoReport v2 API for seamless integration with mobile applications, municipal services, and third-party systems.
Efficient Workflow Management:
Built-in tools help municipal staff manage issue submissions, track progress, and assign tasks, ensuring that problems are addressed from reporting to resolution.
Multi-language & Localization Support:
With built-in support for multiple languages and region-specific configurations, the platform can be tailored to local needs and global standards.
Data-driven Insights:
Analytics and reporting tools provide actionable insights, helping decision-makers prioritize resources and plan improvements effectively.
Customizable & Extensible:
Drupal's flexible architecture allows municipalities to customize workflows, integrate additional features, and expand functionality to suit diverse requirements.

Who Uses Mark-a-Spot?

Mark-a-Spot is designed for:

Municipal Governments & City Administrations:
To streamline citizen reporting and improve the management of civic issues.
Public Service Departments:
To enhance coordination and responsiveness in public service delivery.
Community Organizations:
To foster a participatory approach in addressing local issues.
Civic Tech Innovators:
To leverage an adaptable, open-source solution for developing and deploying civic technologies.

Getting Started

These instructions will guide you through getting a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Install one (or both) of the following toolchains before you begin:

DDEV – recommended local development environment built on Docker
Docker and Docker Compose (v2 docker compose CLI works too)

Installation

Quick start (DDEV) (requires DDEV to be installed first)

git clone https://github.com/markaspot/mark-a-spot.git
cd mark-a-spot
ddev config && ddev start
ddev ssh → ./scripts/start.sh -y

Which environment should I use?

DDEV – best for day-to-day development, automatic HTTPS, and a config you can share with teammates.
Docker Compose – mirrors the legacy stack; handy if you need to run the shipped docker-compose.yml as-is.

The installer always drops and recreates the Drupal database. Back up any local work before rerunning it.

Installer flags (all environments)

-y Autopilot: uses default New York coordinates/locale and skips prompts.
-t Drupal translation import: installs language packs from translations/.
-a AI translation: runs ai-translate.sh to translate default content (needs OPENAI_API_KEY).
Combine as needed, e.g. ./scripts/start.sh -t -a for a multilingual build.
On first run the installer generates a fresh GeoReport API key and prints it. To reuse a specific key, set GEOREPORT_API_KEY in your environment or .env before launching the installer (Docker/DDEV front-end services read the same variable).

AI Translation Feature

The (AI) translation feature allows you to automatically translate the Drupal UI and content artifacts (taxonomy terms, pages, blocks, etc.) using OpenAI's language models. This provides translations for your Mark-a-Spot installation's default content.

To use this feature:

Run ./scripts/start.sh -t -a to use both standard Drupal translation files and AI translation for content
You'll need an OpenAI API key, which you can either:
- Set as an environment variable: export OPENAI_API_KEY=your_api_key
- Enter when prompted during the installation process

The -t -a option will:

Install the selected language in Drupal
Import standard translation files for the Drupal interface
Use AI to translate all default content to the selected language
Set up the site with the translated content as the default content

The translation covers:

Taxonomy terms (categories, statuses, providers)
Static pages (About, Contact, etc.)
Boilerplate content
Block content

Once the script has executed, the application should be accessible at http://localhost or the ddev URLs you will be retrieve via ddev describe.

Please exercise caution when executing the script, as it will drop the database and initialize Mark-a-Spot from scratch. Additionally, familiarize yourself with the Drupal development process, including configuring changes, backing up databases, and other relevant procedures.

Docker Compose workflow

Clone this repository (if you haven't already):

git clone https://github.com/markaspot/mark-a-spot.git
cd mark-a-spot

Start the stack:
```
docker-compose up -d
```
Run the installer:

If the script is not executable, make it so with chmod a+x ./scripts/start.sh.
```
docker exec -it markaspot ./scripts/start.sh -y
```

License

Mark-a-Spot is freely available under the GNU General Public License, version 2 or any later version license.

markaspot / mark-a-spot

Maintainers

Details