mitterio/mitter repository overview

⁠Mitter.io on Docker

Mitter is distributed as a Docker container publicly available on this official Docker Hub page. It contains all the features of the public Sandbox hosted at mitter.io⁠, with the following exceptions:

1. You cannot register for an account or have multiple accounts for your services. Mitter runs in a single tenant mode. You can still however create multiple applications and use them with the same guarantees on data isolation.
2. Certain features like temporary media storage, distributed message broker, event bus is either not available or not supported.
3. If you are using multiple docker containers behind a load balancer, websocket deliveries will work intermittently. This is because there is no exchange of messages and connections between the serving nodes. To be able to serve traffic from multiple nodes, refer to the section 'Configuring an external broker'.

⁠Getting the docker container

Getting the docker container is simple:

docker pull mitterio/mitter:sa

The mitter docker containers support the following tags as per the delivery format of mitter:

1. sa - (AVAILABLE) The standalone build which bundles the platform, dashboard and all dependent servies.
2. latest - Maps to 'sa`

⁠Running the docker container

To run the container, simply execute:

docker run -p11901:11901 -p11902:11902 mitterio/mitter:sa

The two commands that are exposed make the platform and the dashboard available to the host. If you are exposing ports other than the ones mentioned, you will have to specify to the running container how to externally reach the API server. This is required for certain features in the dashboard to work (specifically the user and channels dev panel). To do so:

docker run -eAPI_ENDPOINT='http://localhost:1234'
    -p1234:11901 -p80:11902 mitterio/mitter:sa

Do note that if you do not wish to use the dashboard or do not intend to use the user and channels dev panel, specifying the step above is optional.

⁠Accessing the dashboard

Once the container is running, you can access the dashboard on whichever port you mapped to 11902 on the container. This might take a while.

On the dashboard you can continue to create applications, users, channels etc. as usual.

⁠Building apps with the docker container

The same SDKs and APIs work with your docker container as with the cloud solution. All SDKs provide a way to override the API URL which you must now point to the endpoint serving your docker container (and mapped to docker container 11901).

For specific information on the above, consult the individual SDK documentation.

⁠Persistence

The provided docker image contains the required VOLUME directives for data to be persisted across container runs. For instance, if you were to run a container:

docker run -p.... mitterio/mitter:sa

Assume the container id was 9ba5901f6b80, create users, send messages etc. and then stop the container and restart it:

docker stop 9ba5901f6b80
docker start 9ba5901f6b80

then all the data would be persisted between the two runs. However, the following data will be no longer available:

1. All user authorizations will no longer be available.
2. Any pending message deliveries on websockets will not be persisted and those delivery attempts will be marked as permanent failures on subsequent runs.

We are working on remedies to both the solutions. However, user authorizations will never be completely guaranteed to be persisted between container runs as they are only periodically flushed to the disk.

⁠Backing up volumes

If you wish to keep all data in a location at a convenient place rather than the docker volume storage, the following mountpoints need to be mapped:

1. /data/supernova - This contains all the data from PostgreSQL and Minio.
2. /logs/supernova - This contains all the logs generated by the API server, dashboard and the dependent services (Redis, PostgreSQL, Minio).

⁠Configuring the docker container

The Mitter.io docker container comes with some parameters that are configurable. In its current format the configurability is quite limited and we plan to add a lot more options very soon.

⁠Basic configuration

When running the container the following environment variables can be provided:

1. APP_AUTHORITY_NAME - The name used to issue JWT tokens to users. On the cloud instance it is mitter-io
2. API_ENDPOINT - The publicly resolvable address for the API server.
3. DASHBOARD_ENDPOINT - The publicly resolvable address for the dashboard. This is not required to be modified unless you are extending the docker image and need some services to use the dashboard externally.

⁠Specifying an APPLICATION_CONFIG

To further configure the running services, you can also supply an APPLICATION_CONFIG containing key-value pairs for various properties. The two environment variables used would be:

1. CENTRAL_APPLICATION_CONFIG - This passes an application configuration object to the API server.
2. DASHBOARD_APPLICATION_CONFIG - This passes an application configuration object to the dashboard.

On the command line you would supply them using:

docker run -eCENTRAL_APPLICATION_CONFIG='{\
    "mitter.property": "value"\
}' mitterio/mitter:sa

Since this can get quite lengthy to type and manage on the CLI (especially with the newlines), it is recommended to store the configuration in a file, let's say mitter.api.config and mitter.dashboard.config with the specific JSON and then supply it using:

docker run -eCENTRAL_APPLICATION_CONFIG=`cat mitter.api.config` \
           -eDASHBOARD_APPLICATION_CONFIG=`cat mitter.dashboard.config` \
            -p11901:11901 -p11902:11902 mitterio/mitter:sa

Do note that you cannot nest JSON properties, the entire property path must be specified as a single string in the key. You can, however use integer/boolean values when applicable.

The supported properties are covered in the following sub-sections.

⁠Configuring the signing key for JWTs

By default a random string is used for signing the JWTs for user authorization. This might not always be desired (although will always work if the JWTs are being verified by no other than your running container) and can be overridden using (along with other parameters for JWTs) the following in CENTRAL_APPLICATION_CONFIG:

{
    "mitter.security.jwt.issuer": ".. your issuer name ...",
    "mitter.security.jwt.validity": 1000, // Milliseconds
    "mitter.security.jwt.signing-key": ".. your key, base64 encoded .."
}

⁠Configuring an external broker

To push messages via websockets from multiple docker containers behind a load balancer you will need to enable a rabbitmq server that can act as a central broker between the multiple containers.

A test container can be run simply using:

docker run rabbitmq

Refer to the rabbitmq documentation to find out the following information:

1. The port the RabbitMQ server is running on
2. The username and the password.

Then enable the broker by adding the following in CENTRAL_APPLICATION_CONFIG:

{
    "mitter.delman.websockets.broker.enabled": true,
    "mitter.delman.websockets.broker.host": ".. host ..",
    "mitter.delman.websockets.broker.port": RABBITMQ_PORT,
    "mitter.delman.websockets.broker.username": ".. rabbitmq username ..",
    "mitter.delman.websockets.broker.password": ".. rabbitmq password .."
}

⁠Storing media in S3

If you do not wish to store media from messages (file messages, image messages etc.) locally where your container is running but instead on AWS S3 then you can configure the media storage to do so.

To configure the API server to store media in S3, set the following keys in your CENTRAL_APPLICATION_CONFIG:

{
    "mitter.media.store.minio.enabled": false,
    "mitter.media.store.s3.enabled": true,
    "mitter.media.store.s3.bucketname": ".. S3 bucket to store media in ..",
    "mitter.media.store.s3.aws.access-key": ".. aws access key ..",
    "mitter.media.store.s3.aws.access-secret": ".. aws secret key ..",
    "mitter.media.store.s3.aws.region": ".. aws region ..",
}

⁠Using an event bus

You can also have the docker container send installation-wide events to an AWS SNS topic. The events sent on event bus are extremely granular and can result in a huge flux of messages to your message queue. Most use-cases can be solved by using a simpler and minimal Webhooks interface.

To configure an AWS SNS queue to receive all events on your installation, set the following keys in CENTRAL_APPLICATION_CONFIG:

{
    "mitter.eventing.entbus.enabled": true,
    "mitter.eventing.entbus.sns.topic-arn": ".. aws sns topic ..",
    "mitter.eventing.entbus.sns.aws.access-key": ".. aws access key ..",
    "mitter.eventing.entbus.sns.aws.access-secret": ".. aws secret key ..",
    "mitter.eventing.entbus.sns.aws.region": ".. aws region .."
}