A messaging backend providing a REST API for sending text messages and email. It supports both transactional messages and bulk sending.
- Java JDK 17
- Spring Boot 3.x
- Spring Data JPA
- PostgreSQL
- SMS: Twilio
- Email: Mailgun
- Flyway
- Maven
- Aptible
- JobRunr
- Lombok annotations
- Handlebars (Mustache)
- Apache Commons CSV
These environment variables are key to configuring an instance of this application and must be set managed carefully.
| Variable Name | Description | Notes |
|---|---|---|
| FORCE_SSL | Disallows HTTP and redirects to HTTPS | Set to "true" |
| SPRING_DATASOURCE_URL | PostgreSQL connection URI | E.g., jdbc:postgresql://localhost:5432/messaging |
| SPRING_SECURITY_USER_PASSWORD | Password for Basic Authentication | Saved in a shared folder in LastPass |
| MAILGUN_API_DOMAIN | The appropriate Mailgun domain for the environment | E.g., sandbox610d23a2c4f441c78f8e077c7daf45e0.mailgun.org |
| MAILGUN_API_FROM | An email address using the Mailgun domain | E.g., [email protected] |
| MAILGUN_API_KEY | Mailgun domain sending key | Retrieve from Mailgun |
| MAILGUN_WEBHOOK_SIGNING_KEY | Mailgun webhook signing key | [Retrieve from Mailgun](https://app.mailgun.com/app/sending/domains/{sending domain}/webhooks) |
| TWILIO_ACCOUNT_SID | The appropriate Twilio account identifier for the environment | Retrieve from Twilio account home page |
| TWILIO_AUTH_TOKEN | What is an auth token? | Retrieve from Twilio account home page |
| TWILIO_MESSAGING_SERVICE_SID | Messaging Service identifier within the provided account | Retrieve from Messaging Services page |
All secrets are read from environment variables and kept out of version control. Configuration for secrets required for deployment are set in the deploy.yml file, which use encrypted secret values stored at https://github.com/codeforamerica/messaging/settings/secrets/actions. Any future secrets should be added to the table above, added to the deployment action, and stored in LastPass under the "Shared-Messaging Product" folder.
All other configuration is maintained in conventional Spring Boot application.properties with
application-test and application-ci variations.
Our code style is not strictly followed, but if you wuld like to apply the project defaults, open
IntelliJ Settings/Preferences and go to Editor > Code Style > Java and next to "Scheme" hit the
cogwheel and Import Scheme > IntelliJ IDEA code style XML with
CfaFlavoredGoogleStyle.xml
We use Springdoc-openapi, which helps automate the generation of API documentation in Spring Boot projects. It works by examining an application at runtime to infer API semantics based on spring configurations, class structure, and various annotations. Springdoc is a better supported and more recently updated alternative to Springfox.
This project has configured a custom docs location in application.properties and a Swagger UI can be found at BASE_URL/docs/api/v1 wherever the app is running.
| App | Database | Twilio Account | Twilio Messaging Service | Stack | Environment | Security |
|---|---|---|---|---|---|---|
| messaging-staging | messaging-staging-db | CfA SNIL | messaging-staging | shared-us-west-1 | innovation-lab-staging | Use Basic Authentication with user="user" and password from LastPass |
- We use Dockerfile Deploy
- Configure your git remotes for staging and production, e.g.,
git remote add aptible-staging [email protected]:innovation-lab-staging/messaging-staging.git. - Deploy using git push:
git push aptible-staging main - Alternatively, use the github action to deploy a branch