Packaging your Application for Mosaic¶
Mosaic applications are built on Docker containers. An application is thus defined as a docker-compose file. Here's an example of how the application docker-compose looks like for Element, a Matrix-based chat application we support:
version: '3.9' services: nginx: image: fractalnetworks/element-nginx-proxy:latest environment: LINK_DOMAIN_DEFAULT: $LINK_DOMAIN_DEFAULT element: image: vectorim/element-web:latest synapse: image: matrixdotorg/synapse:latest environment: SYNAPSE_SERVER_NAME: $LINK_DOMAIN_DEFAULT SYNAPSE_REPORT_STATS: "no" entrypoint: "bash -c 'python /start.py generate; python /start.py'" volumes: - fractal-app-volume:/data link: image: fractalnetworks/link:latest environment: LINK: $LINK_DOMAIN_DEFAULT TOKEN: $LINK_TOKEN_DEFAULT EXPOSE: nginx:80 FRACTAL_API: https://gateway.fractalnetworks.co cap_add: - NET_ADMIN volumes: - fractal-link-volume:/root/.local/share/caddy volumes: fractal-app-volume: external: true name: $APP_VOLUME_NAME fractal-link-volume: external: true name: $LINK_VOLUME_NAME
In this file, you can find two unusual things:
linkcontainer. This is a docker container that provides incoming connectivity for the application by connecting to a WireGuard VPN and receiving end-to-end encrypted connection from the outside. It uses Let's Encrypt to provision free, short-lived TLS certificates for itself. It is configured to point to the
nginxcontainer, and it takes a
$LINK_TOKEN_DEFAULTenv variables, which is filled in by the Hive device.
- The volumes, which are declared as external volumes. This is where the Fractal Storage volumes are used, which implement automatic snapshotting and with that replication in an end-to-end encrypted manner.
If you are able to build a Docker image with your application (or a few Docker images, for example if and when you need external tools, such as databases), then it is very easy to convert it into an application that can run on Mosaic.
What you have to keep in mind is that your application will receive HTTP connections from the link
container, not HTTPS. Mosaic works best if you let the link container handle all of the TLS termination
for you. It uses
Caddy to do so, which can be configured to support a lot of modern protocols if you
need, such as HTTP/2 or WebSockets.
The only think you need to worry about is making sure that all of your application state is kept in volumes, so that it can be snapshotted and replicated.
When you publish updates for your application, you must make sure that it will work with data from old versions of the app. This is for example accomplished by running migrations automatically at startup to make sure that the database is in working order.