Machinable gives developers the ability to store and manage their application's data in a structured, validated, RESTful way without having to write any backend code.
See the User Documentation for more information.
Dev Environment
make build up
will install dependencies, build images, and run the necessary containers for a local environment. This includes the postgres, redis, and api containers. The containers are defined in docker-compose.yml
.
NOTE: docker-compose.yml
should only be used for your local development environment, as it uses clear text credentials for the database
You can also refer to the environment in ./local if you need to run all containers (API, Events, Email Notifications, Postgres, Redis, UI).
Build
Build the API docker image.
# install dependencies and build the docker image
$ make build
# run container(s)
$ make up
Hosts
The Machinable API requires a valid hostname (with subdomain) to process requests, so you'll need to update your hosts file to include the following
127.0.0.1 manage.machinable.test
127.0.0.1 some-project.machinable.test
127.0.0.1 another-project.machinable.test
127.0.0.1 manage.machinable.test
is required, the other lines are for any project slugs you need to test locally.
Environment
Set local environment variables
echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > dev.env
source ./dev.env
SENDGRID_API_KEY
is used for the email-notifications, which is used to send emails to users (email verification, misc. notifications).
Configuration
The application config has the following structure:
{
"Version": "0.0.0",
"AppSecret": "",
"ReCaptchaSecret": "",
"IPStackKey": "",
"TemplateMap": {
"default": "/templates/default.html"
},
"SenderName": "Machinable",
"SenderEmail": "[email protected]"
}
Key | Description | Required |
---|---|---|
Version | The version of the API | False |
AppSecret | The secret string used to salt passwords | True |
ReCaptchaSecret | The Google reCaptcha secret used for user registration | True |
IPStackKey | The API Key for IP Stack | False |
TemplateMap | A map of template names to HTML template file paths. inherited from email-notifications | |
SenderName | The name of the email sender. inherited from email-notifications | |
SenderEmail | The email of the sender. inherited from email-notifications |
The secret config values can also be provided as environment variables in docker-compose.yml
:
- APP_SECRET
- RECAPTCHA_SECRET
- IPSTACK_KEY
Testing
Run unit tests with the following command:
# run with make command
$ make test
# run with go test
$ go test ../... -v
CI
Github Tag Action - https://github.com/anothrNick/github-tag-action
See ./github/workflows/main.yml for the full Github workflow.
Packages
Docker Image: machinable
Architecture
API
The Machinable HTTP API is used for all resources of the application (this repo). The API is written in Golang.
Redis
Redis is used as a caching layer for API request counts, as well as a queue for [web hook] event processing.
Postgres
Postgres is the database used to store all data. The JSONB column type is particularly important, as it is how API Resource and Key/Value objects are stored.
See ./sql/create.sql for the full application schema.
Event Processor
The event processor is used to read Web Hook events off of the redis queue and send them to the configured URL.
Email Notifications
The email-notifications container reads notifications from Redis and sends them to the email in the notification body.
Web UI
NOTE: See the UI repository for information on how to run the UI.