Datagram runs as a Docker container. It requires a host running Docker (or boot2docker on Mac), a query storage database (a SQLite file on the Datagram container or other database), and read-only access of your database to run the queries against.
- Docker installed on a host (see installation instructions for your specific host):
- Access to a database to report against
- Creation of a query database to store saved queries
Datagram is configured by two environment variables:
QUERY_DATABASE_URL- The database that Datagram stores user written queries.
REPORTING_DATABASE_URL- The database that Datagram runs queries against. Make sure this is being accessed via a read-only database account
These can be passed on the command line while running Datagram or as an environment file (such as
datagram.env). An example
datagram.env may look like:
In this example, we will run two containers. One will be the storage for the query database and the other will be Datagram itself.
Run a data container to store the query database:
docker run -v /datagram/storage -d --name datagram-data tianon/true
Run the Datagram SQL migrations to create the initial database:
docker run --env-file $(pwd)/datagram.env --volumes-from datagram-data --rm polleverywhere/datagram datagram migrate
Run Datagram on default port 5000:
docker run --env-file $(pwd)/datagram.env --volumes-from datagram-data -p 5000:5000 -d --name datagram polleverywhere/datagram
You should now be able to visit datagram at your Docker host IP via port 5000. You can get the IP address of your boot2docker VM using
When developing on Datagram locally, you can run the application from Foreman without needing to build the application repeatedly in Docker.
Your local development environment should be configured using a
.env file. You can copy the
.env.sample file to
.env and edit it according to your environment.
Run the application with Foreman:
bundle exec foreman start
Now visit Datagram at http://localhost:5000 and you should be ready to write some queries!
Datagram makes no assumptions about security, so make sure you do the following in a production environment:
- Make sure the
REPORTING_DATABASE_URLdatabase is using an account with read-only permissions. You don't want users accidentally deleting data! Your database administrator should be able to set this.
- Its highly recommended that you only make datagram accessible via HTTPS. Transfering your database content over the wire in the clear is not a good idea. We recommend running Datagram behind a load balancer or proxy that supports SSL.
- Datagram provides no authentication or authorizaiton services. The easiest way to implement a username and password is via HTTP Basic authorization through either a rack middleware (building a new Docker image based on this one) or in the proxy configuration over HTTPS.
You've been warned!
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request