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.
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 the API docker image.
# install dependencies and build the docker image
$ make build
# run container(s)
$ make up
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.
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).
The application config has the following structure:
{
"Version": "0.0.0",
"AppSecret": "",
"ReCaptchaSecret": "",
"IPStackKey": "",
"TemplateMap": {
"default": "/templates/default.html"
},
"SenderName": "Machinable",
"SenderEmail": "noreply@machinable.test"
}
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
Run unit tests with the following command:
# run with make command
$ make test
# run with go test
$ go test ../... -v
Github Tag Action - https://github.com/anothrNick/github-tag-action
See ./github/workflows/main.yml for the full Github workflow.
Docker Image: machinable
The Machinable HTTP API is used for all resources of the application (this repo). The API is written in Golang.
Redis is used as a caching layer for API request counts, as well as a queue for [web hook] event processing.
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.
The event processor is used to read Web Hook events off of the redis queue and send them to the configured URL.
The email-notifications container reads notifications from Redis and sends them to the email in the notification body.
NOTE: See the UI repository for information on how to run the UI.