Hint:
This article refers to the on-premises installation of COYO.
Table of content
- Introduction
- System requirements
- Docker
- COYO home directory
- User directories and 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.
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
*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
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:
- 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.
Instructions can be found here
6. REST API
Our REST API provides you with some additional management functions like reindexing the search indices or get the health status of the server and it's also possible to operate all features COYO offers in web and some more like customizing the users' profile fields.