Adding your own containers to Saltbox¶

When you install existing roles in saltbox, some things get handled behind the scenes for you. Notably, this includes creating the subdomain[s] at cloudflare and creating the /opt/APPNAME directory tree.

When you add a container manually as outlined on this page, neither of those things will be done for you (unless you have installed our ddns container), so prior to running the docker commands described below you will have to create the APPNAME.domain.tld subdomain at cloudflare [or wherever your DNS is] and create the required /opt/APPNAME directory tree.

If you want to create a role file that you can install like the built-in applications, see here.

IMPORTANT: APPNAME is a placeholder. You need to change that everywhere it appears to match the application you are installing.

Docker Compose¶

Using Traefik (Authelia)Using Traefik (Authelia + API Router)Using TraefikWithout Traefik


version: "3"
services:
  APPNAME:
    restart: unless-stopped 
Defines the containers restart policy.
Reference

    container_name: APPNAME 
Defines the name of the container.

    image: docker/image:tag Defines the image and tag used when creating the container.

    hostname: APPNAME Defines the hostname used on the Docker network.

    environment: 
Defines the environment variables which are often used to change configuration of the underlying application inside of the container.
While the TZ (Timezone) variable is used in pretty much all containers you will have to figure out the rest as it can differ quite a bit between different containers.

      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    networks: 
Defines which Docker networks the container will join upon creation.
We generally recommend using the saltbox network unless you know what you are doing.

      - saltbox
    labels:
      com.github.saltbox.saltbox_managed: true 
This label will tell Saltbox to manage the container during backups (stopping and starting it).

      traefik.enable: true This label enables router creation in Traefik.

      traefik.http.routers.APPNAME-http.entrypoints: web 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME-http.middlewares: globalHeaders@file,redirect-to-https@docker,cloudflarewarp@docker,authelia@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).
Unless you intend to allow HTTP traffic instead of auto-upgrading to HTTPS make sure to include the redirect-to-https middleware.

      traefik.http.routers.APPNAME-http.rule: Host(`APPNAME.yourdomain.com`) 
This value defines which locations Traefik routes to the application.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME-http.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME.entrypoints: websecure 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME.middlewares: globalHeaders@file,secureHeaders@file,cloudflarewarp@docker,authelia@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).

      traefik.http.routers.APPNAME.rule: Host(`APPNAME.yourdomain.com`) 
This value defines which locations Traefik routes to the application.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME.tls.certresolver: cfdns 
Defines the certificate resolver to use in order to generate a certificate.
If the url is using Cloudflare, with the same account as Saltbox uses, the value should be cfdns.
If you don't use Cloudflare with the URL used or another reason why it cannot use DNS validation use httpresolver.
Remember to enable http_validation in the adv_settings.yml config to enable the httpresolver when using Cloudflare.

      traefik.http.routers.APPNAME.tls.options: securetls@file 
Defines the configuration used for SSL, leave this alone unless you know what you are doing.

      traefik.http.services.APPNAME.loadbalancer.server.port: APPLICATION_PORT Defines which port Traefik routes the traffic to.

    volumes: 
Add any volume mounts the container needs.
/host_path:/container_path

      - /opt/APPNAME:/CONFIG
      - /etc/localtime:/etc/localtime:ro

networks: 
This section tells docker compose that the network is managed outside of this compose file.

  saltbox:
    external: true


version: "3"
services:
  APPNAME:
    restart: unless-stopped 
Defines the containers restart policy.
Reference

    container_name: APPNAME 
Defines the name of the container.

    image: docker/image:tag Defines the image and tag used when creating the container.

    hostname: APPNAME Defines the hostname used on the Docker network.

    environment: 
Defines the environment variables which are often used to change configuration of the underlying application inside of the container.
While the TZ (Timezone) variable is used in pretty much all containers you will have to figure out the rest as it can differ quite a bit between different containers.

      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    networks: 
Defines which Docker networks the container will join upon creation.
We generally recommend using the saltbox network unless you know what you are doing.

      - saltbox
    labels:
      com.github.saltbox.saltbox_managed: true 
This label will tell Saltbox to manage the container during backups (stopping and starting it).

      traefik.enable: true This label enables router creation in Traefik.

      traefik.http.routers.APPNAME-api-http.entrypoints: web 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME-api-http.middlewares: globalHeaders@file,redirect-to-https@docker,cloudflarewarp@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).
Unless you intend to allow HTTP traffic instead of auto-upgrading to HTTPS make sure to include the redirect-to-https middleware.

      traefik.http.routers.APPNAME-api-http.priority: 99 
Defines router priority.
If multiple router paths match a given address the one with the highest priority is used.

      traefik.http.routers.APPNAME-api-http.rule: Host(`APPNAME.domain.tld`) && (PathPrefix(`/api`) || PathPrefix(`/ping`)) 
This value defines which locations Traefik routes to the application.
With the API Router we only add paths to the router that should go around Authelia.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME-api-http.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME-api.entrypoints: websecure 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME-api.middlewares: globalHeaders@file,secureHeaders@file,cloudflarewarp@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).

      traefik.http.routers.APPNAME-api.priority: 99 
Defines router priority.
If multiple router paths match a given address the one with the highest priority is used.

      traefik.http.routers.APPNAME-api.rule: Host(`APPNAME.domain.tld`) && (PathPrefix(`/api`) || PathPrefix(`/ping`)) 
This value defines which locations Traefik routes to the application.
With the API Router we only add paths to the router that should go around Authelia.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME-api.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME-api.tls.certresolver: cfdns 
Defines the certificate resolver to use in order to generate a certificate.
If the url is using Cloudflare, with the same account as Saltbox uses, the value should be cfdns.
If you don't use Cloudflare with the URL used or another reason why it cannot use DNS validation use httpresolver.
Remember to enable http_validation in the adv_settings.yml config to enable the httpresolver when using Cloudflare.

      traefik.http.routers.APPNAME-api.tls.options: securetls@file 
Defines the configuration used for SSL, leave this alone unless you know what you are doing.

      traefik.http.routers.APPNAME-http.entrypoints: web 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME-http.middlewares: globalHeaders@file,redirect-to-https@docker,cloudflarewarp@docker,authelia@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).
Unless you intend to allow HTTP traffic instead of auto-upgrading to HTTPS make sure to include the redirect-to-https middleware.

      traefik.http.routers.APPNAME-http.rule: Host(`APPNAME.yourdomain.com`) 
This value defines which locations Traefik routes to the application.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME-http.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME.entrypoints: websecure 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME.middlewares: globalHeaders@file,secureHeaders@file,cloudflarewarp@docker,authelia@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).

      traefik.http.routers.APPNAME.rule: Host(`APPNAME.yourdomain.com`) 
This value defines which locations Traefik routes to the application.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME.tls.certresolver: cfdns 
Defines the certificate resolver to use in order to generate a certificate.
If the url is using Cloudflare, with the same account as Saltbox uses, the value should be cfdns.
If you don't use Cloudflare with the URL used or another reason why it cannot use DNS validation use httpresolver.
Remember to enable http_validation in the adv_settings.yml config to enable the httpresolver when using Cloudflare.

      traefik.http.routers.APPNAME.tls.options: securetls@file 
Defines the configuration used for SSL, leave this alone unless you know what you are doing.

      traefik.http.services.APPNAME.loadbalancer.server.port: APPLICATION_PORT Defines which port Traefik routes the traffic to.

    volumes: 
Add any volume mounts the container needs.
/host_path:/container_path

      - /opt/APPNAME:/CONFIG
      - /etc/localtime:/etc/localtime:ro

networks: 
This section tells docker compose that the network is managed outside of this compose file.

  saltbox:
    external: true


version: "3"
services:
  APPNAME:
    restart: unless-stopped 
Defines the containers restart policy.
Reference

    container_name: APPNAME 
Defines the name of the container.

    image: docker/image:tag Defines the image and tag used when creating the container.

    hostname: APPNAME Defines the hostname used on the Docker network.

    environment: 
Defines the environment variables which are often used to change configuration of the underlying application inside of the container.
While the TZ (Timezone) variable is used in pretty much all containers you will have to figure out the rest as it can differ quite a bit between different containers.

      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    networks: 
Defines which Docker networks the container will join upon creation.
We generally recommend using the saltbox network unless you know what you are doing.

      - saltbox
    labels:
      com.github.saltbox.saltbox_managed: true 
This label will tell Saltbox to manage the container during backups (stopping and starting it).

      traefik.enable: true This label enables router creation in Traefik.

      traefik.http.routers.APPNAME-http.entrypoints: web 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME-http.middlewares: globalHeaders@file,redirect-to-https@docker,cloudflarewarp@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).
Unless you intend to allow HTTP traffic instead of auto-upgrading to HTTPS make sure to include the redirect-to-https middleware.

      traefik.http.routers.APPNAME-http.rule: Host(`APPNAME.yourdomain.com`) 
This value defines which locations Traefik routes to the application.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME-http.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME.entrypoints: websecure 
Defines the entrypoint used for the HTTP Traefik router.
Leave as is unless you know what you are doing.

      traefik.http.routers.APPNAME.middlewares: globalHeaders@file,secureHeaders@file,cloudflarewarp@docker 
Defines which middleware is used on the router.
A list of currently added middleware can be found on the Traefik dashboard (dash.domain.tld).

      traefik.http.routers.APPNAME.rule: Host(`APPNAME.yourdomain.com`) 
This value defines which locations Traefik routes to the application.
Docs: https://doc.traefik.io/traefik/routing/routers/#rule

      traefik.http.routers.APPNAME.service: APPNAME 
Defines which service the router should route traffic to.

      traefik.http.routers.APPNAME.tls.certresolver: cfdns 
Defines the certificate resolver to use in order to generate a certificate.
If the url is using Cloudflare, with the same account as Saltbox uses, the value should be cfdns.
If you don't use Cloudflare with the URL used or another reason why it cannot use DNS validation use httpresolver.
Remember to enable http_validation in the adv_settings.yml config to enable the httpresolver when using Cloudflare.

      traefik.http.routers.APPNAME.tls.options: securetls@file 
Defines the configuration used for SSL, leave this alone unless you know what you are doing.

      traefik.http.services.APPNAME.loadbalancer.server.port: APPLICATION_PORT Defines which port Traefik routes the traffic to.

    volumes: 
Add any volume mounts the container needs.
/host_path:/container_path

      - /opt/APPNAME:/CONFIG
      - /etc/localtime:/etc/localtime:ro

networks: 
This section tells docker compose that the network is managed outside of this compose file.

  saltbox:
    external: true


version: "3"
services:
  APPNAME:
    restart: unless-stopped 
Defines the containers restart policy.
Reference

    container_name: APPNAME 
Defines the name of the container.

    image: docker/image:tag Defines the image and tag used when creating the container.

    hostname: APPNAME Defines the hostname used on the Docker network.

    environment: 
Defines the environment variables which are often used to change configuration of the underlying application inside of the container.
While the TZ (Timezone) variable is used in pretty much all containers you will have to figure out the rest as it can differ quite a bit between different containers.

      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    networks: 
Defines which Docker networks the container will join upon creation.
We generally recommend using the saltbox network unless you know what you are doing.

      - saltbox
    labels:
      com.github.saltbox.saltbox_managed: true 
This label will tell Saltbox to manage the container during backups (stopping and starting it).

    volumes: 
Add any volume mounts the container needs.
/host_path:/container_path

      - /opt/APPNAME:/CONFIG
      - /etc/localtime:/etc/localtime:ro

networks: 
This section tells docker compose that the network is managed outside of this compose file.

  saltbox:
    external: true