Hint:
This article refers to the on-premises installation of COYO.

Table of content

Introduction
System requirements
Docker
COYO home directory
1. Update COYO
User directories and authentication
1. User directories
2. Authentication
REST API

1. Introduction

Welcome to your new digital home: COYO!

This document will provide you as a system administrator with some basic information about hosting COYO on premise, the system requirements, Docker itself and how we are using this application virtualization technology. Also you'll receive some introducing informations regarding backups, updates, user provisioning, user authentication and our REST API.

All will be provided with helpful links to our knowledge base and documentation.

We hope to answer all your questions on hosting COYO and its technology and recommend you to take notes if something isn't clear.

2. System requirements

Server Software requirements

COYO can be used wherever Docker Compose can be run. Currently this is Linux and Mac OS but we only recommend Linux distributions. We made good experiences with Ubuntu, Debian, RedHat, SLES and CentOS.

Windows Server is not possible because of missing Docker Compose components.

Server Hardware requirements

Our minimum hardware requirement specifications for a single host on premise installation are based on the number of regular users on your COYO social intranet platform.

Bildschirmfoto_2019-09-16_um_11.48.19.png

If you want to run the optional metrics stack to gather data like CPU load, RAM usage and backend insights you would need 10 GB of additional RAM and 2 additional Cores. You'll find more informations about our metrics stack in the Third Party Containers section.

Client Browser requirements

Bildschirmfoto_2019-09-16_um_11.48.33.png

*IE11 is supported but not recommended. For a great user experience use EDGE or another modern browser.

That's all what your client needs.

3. Docker

1024px-Docker__container_engine__logo.svg.png

A DIFFERENT BREED OF VIRTUALIZATION

Docker is used to run application packages called "containers". In a typical example use case, one container runs a web server and web application, while a second container runs a database server that is used by the web application. Containers are isolated from each other and bundle their own tools, libraries and configuration files; they can communicate with each other through well-defined channels. All containers are run by a single operating system kernel and are thus more lightweight than virtual machines, there are more likely a virtualization of just one application instead of a whole OS. Containers are created from "images" that specify their precise contents. Images are often created by combining and modifying standard images downloaded from repositories.

COYO is a Java based application, available as a Docker container, orchestrated together with other containerized applications like PostgreSQL (database) and MongoDB (filestore) with docker-compose.

Hint:
You can read more about Docker in the official Docker Documentation.

3.1 Docker-Compose

an orchestration tool that makes spinning up multi-container distributed applications with Docker an effortless task

Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

With each release we provide a pre-configured YAML file called docker-compose.yml which is kind of our evalution sheet for our orchestration of Docker containers.
The compose file provides all configuration details like public ports, virtual network settings, container links so they can communicate with each other, volume mounts and not to forget the environment parameters for sizing and configuration of more deep components like the backends JVM.
To give you a taste of this technology we will show you the load balancer part of our current compose file:

Bildschirmfoto_2019-09-16_um_11.49.04.png

services: contains all our containers we want to orchestrate.
coyo-lb: is the containers hostname so we can use this shortcut e.g. in linking.
image: is defining from which image the container gets created. If the image is not available locally, Docker will pull it from the Docker Hub.
environment: is where your specific configurations comes in places. We deliver an extra file where all parameters get filled with values.
links: define to which containers this container can talk over all ports inside the virtual Docker network.
volumes: defines mounts into the virtual Docker container. These are important because all data is lost when removing a container except if you mount some volumes into the container from the host.
ports: define the ports exposed. So in this case this is our load balancer and we want it to handle all HTTP traffic so ports 80 and 443 are opened. The other ports are for other public available services.

3.2 Docker Network

Docker creates by default a virtual network bridge and assigns dynamically ip addresses to the containers. This network is not reachable from outside the host. To make containers public you need to configure a port mapping. With our compose file Docker-Compose will create a virtual network called "coyo-default" where only the load balancer is made public. Without any further configuration the IP range for all containers is 172.18.0.0/24.

How you can configure the virtual network of COYO yourself, you will learn in this article.

And if you want to run COYO with a HTTP(S) proxy, check out this article.

Load balancer

All incoming connections are going through the coyo-lb and this load balancer forces a SSL connection so you need a valid certificate to run COYO in our standard setup but it's possible to re-configure this to may use your company's proxy. If you want to change the configuration of our COYO loadbalancer (haproxy) you would need to persist the .conf file and make adjustments.

5601	Kibana: logs of all containers.
5602	Grafana: metrics like CPU and memory usage of all containers.
8083	Backup: create and restore backups using a REST API.
15672	RabbitMQ: overview of the RabbitMQ

Hint:
All other services like database and filestore are not accessible from outside the host

3.3 COYO Containers

COYO stack

Load Balancer	distributes network and application traffic. The load balancer is the only public container.
Backend	is the core that controls the application and databases; it is the internal logic and supervision of the program, it is everything that the user cannot see.
Frontend	contains the visible part of COYO.
Push	processes push messages. For this the server needs access to the public Internet.
Docs	contains the documentation that you will find when you click on "Help" in your COYO.
Backup	creates backups of your COYO platform. More about this here.

3.4 Third Party containers

Dependencies

These are the mandatory dependencies to run COYO like the database and filestore.

PostgreSQL	is the database for storing all COYO contents except files.
MongoDB	saves all files.
Elasticsearch	is a full text search engine that we use for searching in COYO.
RabbitMQ	is a message broker. You can find the web interface behind port 15672.
Redis	is an in-memory database that we use for session caching.
Tika	is a toolkit to extract metadata and content from different file types. We use Tika so that documents about your content can also be found via search.

Logging stack (ELK)

ELK aka Elastic stack is most commonly used in log analysis in IT environments and consists of three different open-source projects. With this stack you can easly browse your log files of all containers with a web interface:

Elasticsearch	is a search and analysis engine for all types of data.
Logstash	is a log pipeline tool that accepts input from various sources, performs various transformations and exports the data to various destinations.
Kibana	is a visualization tool based on Elasticsearch. You can browse through all logs of all containers. Here you can find helpful information for troubleshooting. You can find the web interface behind port 5601.

Metrics stack (PROM) - Optional

Monitor your COYO with the PROM stack! Because this stack needs additional RAM resources and you may already use a monitoring tool in your company this stack is optional and can be started with the advanced start script you'll find in each of our releases.
You'll find interesting metrics about your COYO in our preconfigured Grafana dashboards like CPU and memory usage of each container and many more detailed informations.

Prometheus	is a database optimized for fast, highly available storage and retrieval of time series data in areas such as operations monitoring and application metrics.
Grafana	is an open source software, universal dashboard and graph composer that runs as a web application. You can find the web interface behind port 5602.
cAdvisor	analyses the resource consumption and performance characteristics of running containers.
Exporter	collect different metrics in several containers.

4. COYO Home directory

Each COYO release will provide you with a zip package containing of start/stop scripts, the already mentioned compose file and the important .env file where all your environment parameters are set with defaults.

start.sh	reads the .env and executes the command "docker-compose up" to start all the necessary containers COYO needs to run.
start-advanced.sh	executes the script "start.sh" and additionally starts the metrics stack with Grafana.
stop.sh	executes the command "docker-compose stop" to stop all running containers.
docker-compose.yml	defines the setup and version of COYO. All the parameters you need to configure have been moved to the .env file, so you usually don't need to make any adjustments here. See chapter 3.1 for more information.
.env	contains all configurable parameters necessary for the operation of COYO. To configure COYO, you will need to edit the .env file, where you will overwrite the default values with your individual configuration. For more details on the .env file, see the README.MD file.
.services	similar to .env you will find additional variables to start some services.
teams-messages.env	defines the messages within the Teams Bot.

4.1 Update COYO

When you want to update to a new release of COYO you just need to download the zip package provided at:
https://download.coyoapp.com/release/enterprise/

Just create backup, stop COYO with our provided stop.sh script and unzip and replace all files mentioned above. It's highly recommended to check the .env file for new parameters you may want to adjust in your .env file. The changes of parameters we made with each release you'll find in our release notes:
https://www.service.coyoapp.com/release-notes

5. User directories and authentication

5.1 User directories

When you start COYO for the first time it will use a local user directory. If you want to add a remote user directory this is no problem since you can add as many as you want.

COYO supports the protocol LDAP(S) for user provisioning so directories like MS Active Directory, MS Azure AD and OpenLDAP are no problem at all to integrate.

Instructions can be found here

5.2 Authentication

Besides local authentication with users of the local user directory, users of user directories will authenticate against your user directory over LDAP(S) and you can add other authentication providers as well.

COYO supports authentication over SAML 2.0 and OpenID with its OAuth 2.0 standard so you could easily integrate MS Office SSO, MS ADFS, Google, Facebook, LinkedIn and so on.