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:

https://docs.docker.com/install/linux/docker-ce/centos/#install-docker-ce

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 White Label 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;;
Perform upgrade changes to the Docker image and/or database (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 White Label Agent Docker Image¶

The Web Portal can automatically create a customer Docker Container image using the “White Label” setting values.

There are a number of reasons why you would want to create a custom (White Label) 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.

Customised Client Settings: You require certain custom agent settings. These settings may reflect certain policies or business practices that you wish to enforce on users of the Web Portal.

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).

Customised 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 Customised Container you will need to modify the contents of the standard “Dockerfile” used to build the Docker image.

To build a White Label Docker image, set UseWhiteLabelDockerImage to True. 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 White Label settings.

The general procedure for creating a custom Docker Container image is to modify certain White Label settings, and then run the upgrade_now command as described above in Installing the TeamDrive Agent Docker Image. This process may be repeated until the image is created correctly. The process must also repeated on upgrade of the Web Portal, to ensure that the correct Docker image is used.

A new custom Docker image will not be created if an image with of the required type is already available in the local Docker repository. If you have made changes to White Label settings, and need to rebuild the image then you must use the docker rmi command to remove the image in the archive in order to force upgrade_now to rebuild the image.

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.

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 WhiteLabelProductName 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 Agent archive is downloaded automatically by the Web Portal using the URL specified by the WhiteLabelAgentDownloadURL setting. The URL used also depends on the WhiteLabelProviderCode and WhiteLabelProductName settings, and the version of the Agent to be used.

Since the standard TeamDrive Agent archive always uses the “TMDR” Provider code, if WhiteLabelProductName is set to “teamdrive” or WhiteLabelProviderCode 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 WhiteLabelDockerBuildFolder (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.

If you require Customised Client Settings then you need to customise the contents of the teamdrive.ini file. This is done by adding settings in the WhiteLabelINIFileSettings setting which will write the /etc/teamdrive.ini file during the docker image creation.

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 WhiteLabelProviderCode 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 WhiteLabelDISTRIBUTOR is empty to ensure that the contents of the DISTRIBUTOR file in the archive is not overwritten.

In order to create a Customised Container you need to modify the WhiteLabelDockerfile setting. The WhiteLabelDockerfile 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.

Pre-Installation Tasks¶

Mount the Space Storage Volume¶

Installing Docker¶

Docker CE/EE installation¶

Installing the TeamDrive Agent Docker Image¶

Creating a White Label Agent Docker Image¶

Installing SSL certificates¶

Starting the Web Portal¶

Starting td-webportal¶

Starting the Apache HTTP Server¶

Starting `td-webportal`¶