Docker
This guide explains how to install and run Kyso using Docker and Docker Compose

Prerequisites

  • A Docker-enabled system with proper Docker access
  • Access to Kyso's private docker image hub
  • Internet access
Internet access is only needed during the installation process if Kyso is hosted where it can access Amazon S3 buckets locally

Option 1: Install Kyso with Docker

Set up Kyso container's with a MongoDB database

Pull all the required images

1
docker pull mongo:5.0.5
2
docker pull kyso/backend
3
docker pull kyso/frontend
Copied!
Kyso docker images are not in Docker Hub, so they are not publicly available. In order to download the images, you must have access to our private docker image repository. If you don't have access, please contact us on [email protected]

Prepare the database

Kyso API check on startup if the database has the collections and the minimal data required to run, so you don't need to create any collection or apply any script.
However, it is necessary to configure the user that will have access to the database, and to set the name of the database that Kyso will use.
Create a custom Docker network to allow the containers to discover and communicate with
1
docker network create kyso-network
Copied!
You can change the name of the network (kyso-network) for one of your preference
Create a folder in your local file system, which will store the data of MongoDB outside the container, and another folder to store the initial configuration
1
mkdir mongo-volume
2
mkdir docker-entrypoint.initdb.d
Copied!
Enter into docker-entrypoint.initdb.d folder and create mongo-init.js file with the following contents
1
db = new Mongo().getDB("kyso");
2
3
db.createUser(
4
{
5
user: 'kysodb',
6
pwd: 'kysodb',
7
roles: [{ role: 'readWrite', db: 'kyso' }],
8
},
9
);
Copied!
Please, use strong and unguessable passwords in a production environment
Go back to the original folder and start a MongoDB container
1
docker run -d --name kyso-db \
2
--network=kyso-network \
3
-p 27017-27019:27017-27019 \
4
-e "MONGO_INITDB_ROOT_USERNAME=kadmin" \
5
-e "MONGO_INITDB_ROOT_PASSWORD=ksecret" \
6
-v docker-entrypoint-initdb.d/mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js:ro
7
-v mongo-volume:/data/db \
8
mongo:5.0.5
Copied!
On the first execution, MongoDB will create the users, and once it's finished, the container will shutdown. To run the container again just run the following command
1
docker container start kyso-db
Copied!
To check that the container is running
1
[email protected] % docker ps
2
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
3
03a38df7928b mongo:5.0.5 "docker-entrypoint.s…" 6 minutes ago Up 2 minutes 0.0.0.0:27017-27019->27017-27019/tcp kyso-db
Copied!

Prepare the API

Start a Kyso API container
1
docker run -d --name kyso-backend \
2
--network=kyso-network \
3
-p 3000:3000 \
4
-e "DATABASE_URI=mongodb://kadmin:[email protected]/kyso-initial?retryWrites=true&w=majority" \
5
-e "NODE_ENV=production" \
6
-e "SELF_URL=http://localhost:3000" \
7
-e "KYSO_FILES_CLOUDFRONT_URL=http://url-to-cloudfront" \
8
-e "AWS_REGION=your-bucket-s3-region" \
9
-e "AWS_S3_BUCKET=your-bucket-s3-name" \
10
-e "S3_BUCKET=your-bucket-s3-name" \
11
-e "AWS_ACCESS_KEY_ID=your-aws-access-key" \
12
-e "AWS_SECRET_ACCESS_KEY=your-aws-access-key-secret" \
13
-e "AUTH_GITHUB_CLIENT_ID=your-github-client-id" \
14
-e "AUTH_GITHUB_CLIENT_SECRET=your-github-client-secret" \
15
-e "AUTH_GOOGLE_CLIENT_ID=your-google-client-id" \
16
-e "AUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret" \
17
kyso/backend
Copied!
Please ensure that the DATABASE_URI property matches with the database configuration established in the previous section
To disable social login with Github and Google, just let the environment variables AUTH_GOOGLE and AUTH_GITHUB unset

Prepare the frontend

Start a Kyso container
1
docker run -d --name kyso-frontend \
2
--network=kyso-network \
3
-p 3000:80 \
4
-e "NODE_ENV=production" \
5
-e "API_URL=http://localhost:3000" \
6
-e "NEXT_PUBLIC_API_URL=http://localhost:3000" \
7
kyso/frontend
Copied!
We strongly recommend to use secrets instead of environment variables

Option 2: Install Kyso with Docker Compose

Docker compose is a more simpler way to deploy Kyso, instead of using directly the docker images.
Create a folder in your local file system, which will contain the Docker Compose file, and the initial configuration of MongoDB
1
mkdir kyso-deployment
2
cd kyso-deployment
Copied!
Then, create a new folder inside as follows
1
mkdir docker-entrypoint.initdb.d
2
cd docker-entrypoint.initdb.d
Copied!
Then, create a mongo-init.js file with the following contents
1
db = new Mongo().getDB("kyso");
2
3
db.createUser(
4
{
5
user: 'kysodb',
6
pwd: 'kysodb',
7
roles: [{ role: 'readWrite', db: 'kyso' }],
8
},
9
);
Copied!
Please, change the password to a robust and unguessable one
Then, go to kyso-deployment folder and create a docker-compose.yml file with the following contents
1
version: '3.7'
2
3
services:
4
kyso-db:
5
image: mongo:5.0.5
6
container_name: mongodb
7
restart: always
8
environment:
9
MONGO_INITDB_ROOT_USERNAME: kadmin
10
MONGO_INITDB_ROOT_PASSWORD: ksecret
11
ports:
12
- 27017:27017
13
volumes:
14
- ./docker-entrypoint-initdb.d/mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js:ro
15
16
kyso-backend:
17
image: kyso/kyso-backend
18
container_name: kyso-backend
19
restart: always
20
environment:
21
DATABASE_URI: mongodb://kysodb:[email protected]/kyso?retryWrites=true&w=majority
22
DATABASE_NAME: kyso
23
NODE_ENV: production
24
SELF_URL: http://localhost:3000
25
KYSO_FILES_CLOUDFRONT_URL: http://url-to-cloudfront
26
AWS_REGION: your-bucket-s3-region
27
AWS_S3_BUCKET: your-bucket-s3-name
28
S3_BUCKET: your-bucket-s3-name
29
AWS_ACCESS_KEY_ID: your-aws-access-key
30
AWS_SECRET_ACCESS_KEY: your-aws-access-key-secret
31
AUTH_GITHUB_CLIENT_ID: your-github-client-id
32
AUTH_GITHUB_CLIENT_SECRET: your-github-client-secret
33
AUTH_GOOGLE_CLIENT_ID: your-google-client-id
34
AUTH_GOOGLE_CLIENT_SECRET: your-google-client-secret
35
ports:
36
- 3000:3000
37
links:
38
- 'kyso-db'
39
depends_on:
40
- kyso-db
41
42
kyso:
43
image: kyso/frontend
44
container_name: kyso-frontend
45
restart: always
46
environment:
47
NODE_ENV: production
48
API_URL: http://localhost:3000
49
NEXT_PUBLIC_API_URL: http://localhost
50
ports:
51
- 3001:3000
Copied!
Remember to change the environment variable DATABASE_USE with the password you set up in mongo-init.js
Finally, execute the following command
1
docker compose up
Copied!

Test the installation

In order to check that the API is up and running, just open http://localhost:3000/redoc in your browser
To check that the frontend is up and running, just open http://localhost:3001/login in your browser
Login page