Pre-Installation Tasks

Mount the Space Storage Volume

The container root directory specified by the ContainerRoot setting contains the mount points for all the containers on the Docker system.

The container root (by default /teamdrive) is the mount point for a dedicated file system that provides the requirements outlined in chapter Storage Requirements.

By default, the directory /teamdrive has already been created by the td-webportal RPM package. However, if the Docker host is not the same as the Web Portal machine, then you will have to create this directory yourself.

Note that due to restrictions of the Docker system, all data will be written to this directory as belonging to root.

Mount the file system and create the respective mount entry in /etc/fstab to enable automatic mounting of the file system at bootup. Please consult your Operating System documentation for details on how to perform this step.

Installing Docker

The Web Portal uses Docker containers to run the TeamDrive Agent. A container is started for each user that logs into the Web Portal.

The Docker containers can run on a machine or cluster that is separate from the Web Portal host which handles the login and manages the containers.

Docker can be found in the standard CentOS 7 repositories (CentOS 6 is not longer supported by Docker). CentOS 7 is shipping the commercially supported CS Docker Engine version 1.13 which was released in January 2017 by default. This version will only be updated with security fixes. The TeamDrive Web Portal is still compatible with this version.

In 2017 Docker completely changed their version format, and also changed the name of the Docker Engine package to either Docker Community Edition or Docker Enterprise Edition. The TeamDrive Web Portal supports both versions, but we recommend using the Docker Community Edition.

Docker CE/EE installation

Follow the instructions described on the docker documentation:

By default, the Docker daemon is only accessible via a local socket. The Web Portal requires TCP connectivity. This is the case, even if Docker and the Web Portal are running on the same host.

To make Docker accessible via TCP create a startup option for systemd. Create the folder:

mkdir /etc/systemd/system/docker.service.d

and create this file:

/etc/systemd/system/docker.service.d/startup_options.conf

with the following content:

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd

using this call from the command line:

echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/dockerd" >> /etc/systemd/system/docker.service.d/startup_options.conf

Reload the unit files:

systemctl daemon-reload

Create the file /etc/docker/daemon.json and add this hosts configuration:

{
"hosts": ["tcp://127.0.0.1:2375"]
}

using this call from the command line:

echo -e "{\n        \"hosts\": [\"tcp://127.0.0.1:2375\"]\n}" >> /etc/docker/daemon.json

After restarting Docker with:

service docker restart

the Docker API will be available on port 2375.

On the client side (the Web Portal host) you will now need to set the DOCKER_HOST environment variable in order to use the docker command. Replace localhost below with the domain name of the Docker host:

[root@webportal ~]# export DOCKER_HOST=tcp://localhost:2375
[root@webportal ~]# docker images

To have this environment variable automatically set at the login, add the two lines to the bash_profile of the root user by executing:

[root@webportal ~]# echo DOCKER_HOST=tcp://localhost:2375 >> /root/.bash_profile
[root@webportal ~]# echo export DOCKER_HOST >> /root/.bash_profile

Installing the TeamDrive Agent Docker Image

Note

If you are using a Registration Server that is not attached to the TeamDrive Network, or you are using a customised (“White Label”) version of TeamDrive, please go to the next chapter Creating a Customised Agent Docker Image. Otherwise proceed with the following standard installation and skip the next chapter.

Docker Container images are available from the TeamDrive public Docker repository on the Docker hub. Here you will find a list of the tagged images that have been uploaded by TeamDrive:

https://hub.docker.com/r/teamdrive/agent/tags/

The current version of the TeamDrive Agent used by the Web Portal is stored in the MinimumAgentVersion setting. The ContainerImage setting stores the name of the Container image currently in use by the Web Webportal. If the version of the Agent in ContainerImage is less than MinimumAgentVersion it will be automatically updated.

If this required images does not exist in the local Docker repository then it will be automatically pulled from the Docker hub and installed on your docker host.

If a more recent version of the Image is available from the Docker hub, then this version will be used in place of version specified by ContainerImage and by MinimumAgentVersion.

To install or update the Container image used by the Web Portal use the upgrade command: start yvva and execute upgrade_now;;:

[root@webportal ~]# yvva
Welcome to yvva shell (version 1.3.8).
Enter "go" or end the line with ';;' to execute submitted code.
For a list of commands enter "help".

UPGRADE COMMANDS:
-----------------
To upgrade from the command line, execute:
yvva --call=upgrade_now --config-file="/etc/yvva.conf"

upgrade_now;;
Upgrade the database structure and Docker container image (this command cannot be undone).

Leave the yvva shell by typing quit.

Note

If outgoing requests has to use a proxy server, follow the Docker documentation https://docs.docker.com/engine/admin/systemd/#http-proxy to set a proxy for Docker. Restart the Docker service after adding the proxy configuration.

Creating a Customised Agent Docker Image

The Web Portal Docker image builder can be customised to create a container image specialised for your purposes.

There are a number of reasons why you would want to create a custom Docker image:

  • Standalone Registration Server: You are using a Registration Server that is not connected to the TeamDrive Registration Server Network via the TeamDrive Name Server (TDNS). In this case you are using a standalone Registration Server or your own TeamDrive Network of Registration Servers.
  • Custom Agent Archive: You have a white label agreement TeamDrive that requires customisation of the TeamDrive Agent binary or the Web user interface (the Web-GUI).
  • Specialised Container: You are using the Web Portal to integrate other applications into the TeamDrive Network which require changes in the behavior of the Docker Container (for example, addition binaries must be started in the container).

If you have a Standalone Registration Server or require Customised Client Settings you will have to modify the contents of the standard DISTRIBUTOR file.

In the case of Custom Agent Archive you require a custom “Agent archive” (a .tar.gz file) created by TeamDrive and available for download from the TeamDrive archive download portal.

If you require a Specialised Container you will need to modify the contents of the standard “Dockerfile” used to build the Docker image. This is done by setting the contents of the BuildDockerfile setting.

If you need to set specific TeamDrive client settings for the TeamDrive agent running in the container, then this can be done using the SharedIniPath and ClientSettings settings. There is no need to create a custom container for this purpose. Previously the setting WhiteLabelINIFileSettings was previously used for this purpose, but this setting has been deprecated.

The details of building a custom docker image, and making the required modifications is described below. Further information can be found in the descriptions of the Build Image settings.

In order to build a Docker image, the Web Portal needs an “Agent archive”. This is either a standard TeamDrive Agent archive, or a Custom Agent Archive built by TeamDrive for customers as part of a White Label licensing agreement. Custom Agent archives must have a different “Product name”. The standard Product name is “teamdrive”. The Product name is specified in the BuildProductName setting, and must be changed if you are using a custom Agent archive.

The Agent archive includes the TeamDrive Agent binary and other support files require to run the executable. Custom Agent archives may include changes to the TeamDrive Agent binary, to the Web-GUI and to the DISTRIBUTOR file included in the archive.

The version of the Agent used is determined by the MinimumAgentVersion and ContainerImage settings. The highest version specified by these two settings will be used by the Web Portal, unless an even higher version of the Agent is found on Docker hub.

The Agent archive is downloaded automatically by the Web Portal using the URL specified by the AgentDownloadURL setting. The URL used also depends on the BuildProviderCode and BuildProductName settings, and the version of the Agent to be used.

Since the standard TeamDrive Agent archive always uses the “TMDR” Provider code, if BuildProductName is set to “teamdrive” or BuildProviderCode is set to “TMDR”, the download URL will used will always be:

https://s3download.teamdrive.net/{VERSIONSHORT}/TMDR/linux-x86_64/teamdrive_agent_{VERSION}_el7.x86_64.tar.gz

Before downloading the Agent archive, the Web Portal will check if the required archive is already available in the ImageBuildFolder (the build directory). If so, the archive will not be downloaded. If not, the Web Portal searches the build directory for archives with a higher version number. If found this Agent archive will be used instead of the version specified by MinimumAgentVersion or ContainerImage.

The general procedure for creating a custom Docker Container image is to modify certain build settings, and then run the upgrade_now command as described above in Installing the TeamDrive Agent Docker Image. If you remove the Docker image just created you can repeat this process until the image is built correctly. In other words, use the docker rmi command to remove the image in the local archive so that upgrade_now will rebuild the image.

Since a new custom Docker image will not be created if an image with the required TeamDrive agent already exists, if you make changes to build settings, you must remove the current docker image and run upgrade_now to apply the new settings.

The upgrade_now command must also be run on upgrade of the Web Portal, to upgrade the TeamDrive agent version used. This will also create a Docker image with the updated version number.

If you are using a Standalone Registration Server, you might need a customised client that will reference your Registration Server. This depends on your provider configuration.

Note

If you change the contents of the DISTRIBUTOR file you must set the Provide code in the DISTRIBUTOR file, and set BuildProviderCode to the same value. In the DISTRIBUTOR file the Provider code is set as follows: code=<provider-code>.

If you are using a custom Agent archive which includes a customised DISTRIBUTOR file then make sure that DISTRIBUTORFile is empty to ensure that the contents of the DISTRIBUTOR file in the archive is not overwritten.

In order to create a Specialised Container you need to modify the BuildDockerfile setting. The BuildDockerfile value is the contents of the Dockerfile which is used by docker to build a new TeamDrive Agent image, as described in the Docker documentation: https://docs.docker.com/engine/reference/builder/.

Installing SSL certificates

The default Apache HTTP Server installation ships with self-signed SSL certificates for testing purposes. We strongly recommend to purchase and install proper SSL certificates and keys and to adjust the configuration in file /etc/httpd/conf.d/ssl.conf accordingly before moving the server into production.

The exact installation process depends on how you obtain or create the SSL key and certificate, please refer to the respective installation instructions provided by your certificate issuer.

Starting the Web Portal

After all configuration steps have been performed, we can start the TeamDrive Web Portal to conclude the initial installation/configuration.

Starting td-webportal

To activate the yvvad-based td-webportal background task you have to start the service using the provided init script.

The configuration file /etc/td-hosting.conf defines how this process is run. You usually don’t have to modify these settings.

To start the td-webportal program, use the service command as user root:

[root@webportal ~]# service td-webportal start
Starting TeamDrive Web Portal:                       [  OK  ]

Use the status option to the service command to verify that the service has started:

[root@webportal ~]# service td-webportal status
yvvad (pid  2506) is running...

If td-webportal does not start (process yvvad is not running), check the log file /var/log/td-webportal.log for errors. See chapter Troubleshooting for details.

Starting the Apache HTTP Server

Now the Apache HTTP Server can be started, which provides the TeamDrive Web Portal functionality via mod_yvva.

You can start the service manually using the following command:

[root@webportal ~]# service httpd start

Warning

At this point, the Web Portal’s web server is answering incoming requests from any web client that can connect to its address. For security purposes, you should not make it accessible from the public Internet until you have concluded the initial configuration, e.g. by blocking external accesses using a firewall.

Check the log file /var/log/httpd/error_log and /var/log/td-webportal.log for startup messages and possible errors:

[notice] Apache/2.2.15 (Unix) mod_ssl/2.2.15 OpenSSL/1.0.1e-fips configured
-- resuming normal operations
[notice] mod_yvva 1.3.1 (Jan 15 2016 12:56:45) loaded
[notice] Logging (=error) to: /var/log/td-webportal.log

Please consult chapter Troubleshooting if there is an error when starting the service.