Server installation

Installation guide - 1.8+

In this guide, we want to show how to install the Wallboard server environment. There is an option to install our system without docker but we highly recommend it, because all of our reference systems and examples based on docker.

Server-prerequisites.

Optional remote management - if you want us to install, update or maintain your server

Important: Please contact us before doing anything (except the prerequisites)!

Please double-check that the ports are open!

Fill our install form with all the required details.

We are using Docker and Portainer to install and manage the Wallboard system. Through Portainer we have full control over the containers on the system. We only maintain servers with this tool. You can find any security information about it in our security whitepaper

Docker install on the host

  1. You can find the installation guides for all supported OS on the docker site. For example, the following link points to the CentOS guide but on the left menu, you are able to check the guide for any other OS.

Install Portainer

Run the following command in Terminal (CLI) or PowerShell to install the Portainer container.

Change the {PATH_ON_HOST} with the path on your host machine where you want to install the Portainer application.

If you do it on Windows 10, add a slash to the beginning of the path, remove the colon after the disk drive letter and replace the backslashes with slashes.

Executing the following command will only make the Portainer available from the server machine.

If you want to access it from another machine, delete the localhost IP (127.0.0.1): “127.0.0.01:9000:9000” -> “9000:9000”

Example: C:\Docker\Portainer -> /C/Docker/Portainer

docker run -d -p “127.0.0.01:9000:9000” --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v {PATH_ON_HOST}:/data portainer/portainer

Portainer configuration

  1. Configure an administrator user
    • Open localhost:9000 or server’s IP:9000 on a browser and configure an administrator user.
  2. Configure Local environment
    • Choose the local Docker environment and then click the connect button.
  3. Configure Docker Hub authentication
    • Important: To pull our images we have to give access to the Docker user that is reserved for our partners! Contact us for access!
    • Configure registry authentication with the provided Docker Hub credentials and then click the update button.

Preparing for installation

Our Nginx container is necessary for proxying the web requests to the right services (e.g.: Wallboard Content Editor, N8N, PM2).

Optional: Create certificate (Let’s Encrypt)

To enable HTTPS on your website, you need to get a certificate from a Certificate Authority (CA).

We are using Certbot (create/manage Let’s Encrypt certificates) for that.

You can create a Let's Encrypt SSL certificate with the following command.

It does the next things:

  • Runs a Certbot docker container to create a Let's Encrypt SSL certificate for your domain ($DOMAIN).
  • The created certificate will be stored in the chosen path on the host server ($CERTS_DIR).
  • Your email ($EMAIL) will be added as a notification address.
    • You will receive notifications for example about expiration.

Before executing make sure that it is able to communicate on port 80.

docker run -it --rm -v $CERTS_DIR:/etc/letsencrypt –v $CERTS_DIR:/var/log/letsencrypt -p 80:80 certbot/certbot certonly --standalone --email "$EMAIL" --agree-tos -d "$DOMAIN"

You should overwrite the following parts:

  • $CERTS_DIR = Change to the path on your host where do you want to create the certificate.
  • $EMAIL = Change to your email address.
  • $DOMAIN = Change to the domain you want the certificate for.

Example:

  • Your domain is testdomain.wallboard.Geomant.com
  • You want to save this certificate to /etc/letsencrypt
  • You want to get notifications on notifications@wallboard.geomant.com

docker run -it --rm -v /etc/letsencrypt:/etc/letsencrypt –v /etc/letsencrypt:/var/log/letsencrypt -p 80:80 certbot/certbot certonly --standalone --email "notifications@wallboard.geomant.com" --agree-tos -d "testdomain.wallboard.Geomant.com"

The Certbot container will renew your certificate automatically, for that you should overwrite the $CERTS_DIR/renewal/$DOMAIN.conf file as follows:

  • Change the authentication from standalone to webroot
  • Add the following lines to the end of the file (change $DOMAIN to your domain):

[[webroot_map]]

$DOMAIN = /var/www/letsencrypt

Good to know

  • We are suggesting to use a central folder on your host to store there all your data, for example /srv/docker or /c/docker.
  • Use spaces instead of tabs, because tabs will not work properly in .yml file.
  • The volumes look like: /path/on/host:/path/in/container
    • You have to configure only the left side from the colon
    • If you want to use our system on Windows, use the format of the path shown in the example (like on Linux)
      • g.: /C/Docker/Wallboard/mysql
  • Memory limits are configured for an 8GB system, but you can modify them as you wish.
    • You can control the memory limit of each container with the mem_limit variable.
      • g.: mem_limit: 1536m -> will limit the maximum RAM usage of the container to 1536MB (1.5GB)
    • The memory limit for the master container is the value of –Xmx variable at the JAVA_OPTS environment.
  • Do not modify the part after the colon for any volume below the container’s volume section!
  • A variable {VARIABLE_NAME} can occur in multiple containers and its value must be the same, pay close attention to this!

Install Nginx and Certbot

In the following, we only list the settings that can be changed!

Contact Geomant for details.

Configuration

Nginx

Contact Geomant for details.

You should overwrite the certificate paths following:

  • The /etc/ssl is a static folder, where you will mount your certificates folder. Do not change this part!
    • Example 1:
      • We have created certificates with certbot to the /etc/letsencrypt.
      • We will mount the /etc/letsencrypt folder where we have the certbot certificates to the container at /etc/ssl.
      • The certificates are in the /etc/letsencrypt/live/{DOMAIN}/ folder
      • We have to change the host path to the mounted path and the result will be:
        • ssl_certificate /etc/ssl/live/{DOMAIN}/fullchain.pem;
        • ssl_certificate_key /etc/ssl/live/{DOMAIN}/privkey.pem;
      • So if you are using Certbot, you just have to overwrite the other 2 {DOMAIN} to your domain.
    • Example 2:
      • We have our own certificate in the /home/own_certificates.
      • We will mount the /home/own_certificates folder where we have the certificates to the container at /etc/ssl.
      • The certificates are in the /home/own_certificates folder
      • We have to change the host path to the mounted path and the result will be:
        • ssl_certificate /etc/ssl/certificate.crt;
        • ssl_certificate_key /etc/ssl/private.key;

Copy the modified file to a folder on your host. (e.g.: inside of /srv/docker/nginx/sites-enabled/index.md).

Volumes:

You can change the device’s value under the volume name in the volumes section at the end of the file. The volume name is the text before the colon under the Nginx’s volumes part.

Don’t modify the part after the colon.

  • certificates: Set the folder that contains your certificate. In case of Let’s Encrypt certificate (created with Certbot), you have to set to that path you executed the certificate creation ($CERTS_DIR) because the $CERTS_DIR/live/ folder contains only links to the certificates.
    • You can change the value of this volume under the volumes part at the end of the compose file.
      • Default value is /etc/letsencrypt.
      • Based on the previous example, if you have your own certificate this value will be /home/own_certificates.
    • sites_enabled: Set the folder that contains your app-wb.conf file.
      • Default values is /srv/docker/nginx/sites-enabled
    • well_known: This is a volume for Certbot renew, if you have your own certificates, feel free to remove from compose.

In case you changed the subnet in the Nginx's docker-compose file:

  • Update the container's IP with the new subnet!
    • This also applies to the IP's in the other compose files!
  • Get site_variables.conf file, update the IP's with the new subnet and mount the configured file for the Nginx container.

You can bind mount if you add a new line to the Nginx volumes.

Example:

  • "- /srv/docker/nginx/sites_variables.conf:/etc/nginx/site_variables.conf"
    • The part before the colon is the absolute path of the configured .conf file on your server.
    • The part after the colon is permanent, so don't modify it!
Certbot

You do not need to change this container. If you have your own certificates, you should remove them from the compose.

Compose-up

    1. Choose the local endpoint at Portainer's Home page
      1. Choose the Stacks option and then click the Add stack button.
      2. Give a name to this stack and copy the content of the configured .yml file to the web editor section.
      3. Click the Deploy the stack button at the bottom of the page and wait until Docker completes the installation.

Install Wallboard system

Configuration

Contact Geomant.

Database

The database passwords must be the same at master and database, and once the installation is complete, you shouldn't change the values!

You should modify just the following parts:

Environments:

  • MYSQL_DATABASE={DATABASE_NAME}
    • {DATABASE_NAME}: Set the desired database name. This variable occurring in the master container and should be the same value!
  • MYSQL_PASSWORD={DATABASE_PASSWORD} and MYSQL_ROOT_PASSWORD={DATABASE_PASSWORD}
    • {DATABASE_PASSWORD}: This value will be the password for your database. This variable occurring in the master container and should be the same value!

Volumes:

  • /srv/docker/mysql: default storage path of the database application. Change it if you want to store the database files elsewhere.
    • This folder does not have to exists, Docker will create if not.
    • If it exists, it must be empty!
Master

For the following variables that have a default value, you only need to leave the field in the compose file if you want to use a value other than the default, otherwise, delete that field from the file. Where there is no default value, those fields are mandatory to fill!

Environments:

  • JAVA_OPTS:
    • Xms= The initial memory size (initial heap size).
    • Xmx= The memory limit for the master container (maximum heap size).
    • Depends on RAM size, our suggestions (format is: "XXXXm" - means XXXX megabyte):
      • Host RAM size 4GB → Xmx=1536m
      • Host RAM size 8GB → Xmx=4096m
      • Host RAM size 16GB → Xmx=8192m
  • server-name=
    • The value of this field must be set and must be unique, which is used to identify the server on the Wallboard license server!
    • We recommend using your company name without spaces and special characters, if you want to install more than one server, then add numbers in ascending order to the end of the value. Example below:
      • Value at first installation process: YourCompanyNameWithoutSpacesAndSpecialCharacters1
      • Value at second installation process: YourCompanyNameWithoutSpacesAndSpecialCharacters2
      • Value at third installation process: YourCompanyNameWithoutSpacesAndSpecialCharacters3
  • product-name=
    • This value is used for branding tab title (Login {product-name}, e.g: Login wallboard), the default value is wallboard.
  • master-protocol=
    • Your server's protocol, https or https.
    • This variable ({PROTOCOL}) occurring in several containers and should be the same value!
  • master-host=
    • The value of this field must be the server's static IP or domain without the protocol because if it is not, the content editor will not work properly (default value is localhost)!
    • e.g.: from https://editor.wallboard.geomant.com, we need here only the editor.wallboard.geomant.com part!
    • This variable ({DOMAIN}) occurring in several containers and should be the same value!
  • master-defaultadmin=
    • The value of this field will be the default admin's email, default value is admin@wallboard.geomant.com.
    • You can login with this email and the password will be "password" for the first time. We recommend to change the password immediately or delete the user and create a new one.
  • apk-base=
    • The value of this field will be the android application base, default value is MSD-Wallboard-Client-.
    • You only have to configure it if you have a white-labeled android application.
  • database-host=
    • The hostname of the database application, set only if you have changed it at the database compose (default value is database), otherwise, delete the field from the compose file.
  • database-name=
    • Name of the database.
    • Should be the same value as the MYSQL_DATABASE field at the database compose!
  • database-password=
    • The password of the database.
    • Should be the same value as MYSQL_PASSWORD and MYSQL_ROOT_PASSWORD field at the database compose!
  • *max-upload-file-size=*
    • Defines the maximum uploadable file size.
    • The default value is 1024MB.
  • TZ=

Volumes:

  • You can change the default storage path of the main application. For that, you have to configure the left side from the colon at the volume section
    • This folder does not have to exists, Docker will create if not.
    • If it exists, it must be empty!

Networks:

  • {NGINX_NETWORK}: Replace with the Nginx's network name:
    • You can find the network's name in the Nginx container's details.
    • Go to the Stack page and select the stack you created earlier for Nginx and click on the Nginx container name to open the details.
    • You can find the container's network at the bottom of the details.

Compose-up and validate Wallboard system

  1. Create a new stack (name e.g: master) and repeat the compose-up steps you have done at Nginx install above.
  2. If you install an online server, you should inform us after a successful installation, because we have to approve the new server connection and we have to configure a license for the server. We have to approve the server’s license on the first run, without it, the server cannot be run properly!
  3. You can reach the content editor on the value of the - master-host field, you can login with the value of the - master-defaultadmin field and the password will be "password" for the first time. You will be prompted to change your password when you log in for the first time!
  4. You can configure your system under the Administrator -> System settings menu.
    • Here you will find the main setting options including the white-labeling option.

A detailed description of the system and features can be found in our knowledge base:

If you have any concerns or questions, feel free to contact us on:

Plugin manager sub-systems

These plugins are optional, but without them, some features may not work properly or may not work at all.

Other utility services

These services are optional, but without them, some features may not work properly or may not work at all.

Optional services

Further configuration and customization

Sorry, your browser does not support inline SVG. article updatedarticle updated5/13/2022 9:55:30 AM (UTC)5/13/2022 9:55:30 AM (UTC)