IDOML server - jupyterhub

Welcome to IDOML jupyterhub server deployment guide.

In this repository you will find the configuration files to deploy the IDOML jupyterhub server.

Requirements

Hardware Requirements:
- A linux server. Please refer to jupyterhub ressources estimation.

Clone the IDOML jupyterhub repository:

HttpsSSH

git clone https://github.com/serval-uni-lu/idoml-jupyterhub.git
cd idoml-jupyterhub

git clone git@github.com:serval-uni-lu/idoml-jupyterhub.git
cd idoml-jupyterhub

To deploy the IDOML jupyterhub server, ensure your system meets the following requirements:
- Docker: IDOML utilizes Docker for deployment. Refer to the official Docker documentation for installation instructions.
- Docker-compose: Docker-compose is required for orchestrating the deployment process. Follow the installation instructions provided in the official Docker-compose documentation.
Be sure that the IDOML server is already running!! The jupyterhub is using keycloak for user authentification.
Before deploying IDOML, update the .env file with the necessary configurations:
- Domain name Configuration:
  
  We expect that the user dispose a custom domain name. Please redirect all the subdomains to the server's IP address. Then update the .env file with the variable IDOML_DOMAIN. This domain will be used to access the services deployed on the server.
  
  Deploying on localhost
  
  If you do not have a custom domain name, you can use the default domain name which is a subdomain of localhost. It should be able accessed from the server itself.
  Manual domain name configuration
  
  If you don't have a domain name, but you want to deploy the IDOML platform on a remote server, you can manually configure the /etc/hosts file on your local machine. Suppose that the remote server IP address is a.b.c.d. In this case, you can add the following line to the /etc/hosts file on your local machine:
```
a.b.c.d idoml.com keycloak.idoml.com airflow.idoml.com dashboard.idoml.com minio.idoml.com console.minio.idoml.com jupyterhub.idoml.com idoml.mlflow.idoml.com
```
  In this example, the IDOML_DOMAIN should be set to idoml.com.
  
  It should be done on the local machine where the browser is running and the server deploying the IDOML platform. This configuration is only for testing purposes and should not be used in a production environment.
- Set up jupyterhub crypt key:
  
  Run the following command to update the .env file:
```
echo -e "JUPYTERHUB_CRYPT_KEY=$(openssl rand -hex 32)" >> .env
```

Deployment

Once the requirements are met, the IDOML jupyterhub server can be deployed using the magic command at the root of the project folder:

docker compose up -d

Note

As some docker images are still private, please ensure that you have access to the packages from the Serval GitHub before deploying the platform. Before deploying the platform, please ensure that you have logged in to the GitHub Docker registry.

Try it out

The platform is now accessible via the domain name you have set up. The IDOML dashboard can be accessed at the following URL:

http://jupyterhub.{IDOML_DOMAIN}

Where {IDOML_DOMAIN} is the domain name you have set up previously in the .env file.