Make sure your Swarm Project works on Quantum #

Best Practices #

Planetary Quantum makes a few Docker Swarm best practices manditory:

No host-directory bind mounts
For persistant runtime data, e.g. for Databases, use Docker volumes instead. In some cases, it may be a good idea to create these volumes manually outside your stack and use them via external: true - just to make it even harder to accidentally delete them. However, even “internal” volumes are not deleted on stack deletion by default.
For configuration files, use a Dockerfile to COPY them directly into your images. Alternatively, generate any configuration on container startup from environment variables (many popular images already support environment variables for important settings).
Don’t use :latest
Use specific versions for your images instead.
Details
That makes it easier to see what's deployed, easier to repeat the exact same deployment, and easier to roll back. Also, in some circumstances, images on `:latest` are not guaranteed to update to the latest version on deployments, which may be surprising. Explicit image versions don't have that problem.
All images must come from a registry
While this is not enforced, we strongly recommend building images outside Quantum and pushing them to a registry - and then using them as in:
```
image: my.registry.example.com/my/image:1.0.0`
# or, for images from docker hub
image: alpine:version
image: gitlab/gitlab-ce:version
```
Details
Moving/scheduling containers on multi-node clusters only works when all images come from a registry. And even on one-node setups, only images from registries make many of Docker Swarm's features possible - from rollbacks, to general repeatability of deployments and so on. You *can* build images directly on Quantum, and you *can* use those in your stacks - but doing so comes with so many caveats that we would never recommend doing that, not even for debugging purposes. Building on your cluster requires resources. The resources required for building may put stress on your cluster and impact your applications' availability and response time. Depending on the type of application and the code that gets included in the images, you may also need to distribute private keys and credentials to `git clone` the required code. Long story short: use your CI/CD pipeline to create images. That said - for local development setups, local "un-pushed" images might be fine. But they're not appropriate for deploying on Planetary Quantum.
On multi-node clusters, pin volume-using services to specific nodes
Volumes don’t automatically travel when services are re-scheduled to run on a different node. Thus, databases and similar services should either be pinned to a specific node or (advanced) have a setup where they can run in global mode. Usually, one would use something like:
```
deploy:
  placement:
    constraints: 
      - node.label == node01
```

Limitations #

The nature of Planetary Quantum’s management console dictates a few more limitations:

Stack names must be globally unique
We recommend using your cluster/endpoint name in the stack name (so your-app-your-cluster) or similar. quantum-cli will also explain that, if you try to use a stack name that’s already in-use.
TCP port 9001 cannot be opened to the internet
That port is used to connect the Quantum console to your cluster. You can, of course, use 9001/tcp internally between containers, and in networks you create.
Do NOT use docker-compose build to build images
Instead, use docker build/docker push with normal Dockerfiles.
Details
The Quantum console uses Docker labels for parts of its functionality. `docker-compose build` bakes some `com.docker.compose...` labels into the images themselves, thereby confusing the console, which may lead to containers not appearing in some views, etc. You can use other container labels without limitation, this is just about how `docker-compose build` works.