Cloud Deployment

Scoold can be deployed to any cloud provider that supports Docker containers or Java applications.

Scoold Cloud fully managed

We offer managed cloud hosting for Scoold Pro at ↗ cloud.scoold.com. Scoold Cloud offers fully managed Scoold hosting with automatic updates, backups, and security patches. With Scoold Cloud you can get a Scoold Pro server up and running in minutes, without worrying about deployment or maintainance.

On Scoold Cloud you get:

• A dedicated Scoold Pro instance with all features
• Dedicated subdomain with SSL
• Data encryption at rest
• Custom domain support
• Web admin console for easy configuration
• 2 months free, for annual subscriptions

Visit Scoold Cloud →

Heroku

1. Click the button to open Heroku
2. Launch a new node by filling in the required parameters

Manual deployment - code push

1. Clone this repository and create a new Heroku app
2. Add Heroku as a Git remote target and push your changes with git push heroku master
3. Go to the Heroku admin panel, under “Settings”, “Reveal Config Vars” and set all the configuration variables shown above but replace all dots in the variable names with underscores, e.g. scoold.para_endpoint -> scoold_para_endpoint.
4. Open the app in your browser at https://{appname}.herokuapp.com.

Manual deployment - JAR push

1. Build the Scoold JAR file or ↗ buy a Scoold Pro license
2. ↗ Download and install the Heroku CLI
3. Create a Heroku app or use the id of an existing Heroku app where you want Scoold deployed
4. Add the heroku/jvm and heroku/java buildpacks to your Heroku app from the Settings page
5. Create a file Procfile containing this line:

   Procfile

   web: java -Dserver.port=$PORT $JAVA_OPTS -jar scoold-*.jar $JAR_OPTS

6. Open a terminal in the directory containing the JAR file and execute:

   heroku plugins:install java
   heroku deploy:jar scoold-x.y.z.jar --app myscooldapp

Pushing JARs to Heroku is useful in cases where you have an existing Heroku app which hosts a free version of Scoold, deployed through the “one-click” Heroku button, and you want to upgrade it to Scoold Pro.

On Heroku you don’t have a configuration file, instead you use Heroku’s environment variables to configure Scoold. You can add each Scoold configuration property as an environment variable on the Settings page of your Heroku admin page. Click “Reveal Config Vars”. Configuration variables (config vars) must not contain dots ”.”, for example scoold.para_endpoint becomes para_endpoint. You must replace every dot with an underscore in order to convert a Scoold configuration property to a Heroku environment variable.

Installing the Heroku CLI tool allows you to watch the Scoold logs with:

heroku logs --tail --app myscooldapp

Or you can restart your dyno with:

heroku restart --app myscooldapp

Heroku container

You can also run Scoold as a Docker container on Heroku:

heroku create my-scoold-app
heroku container:login
heroku container:push web -a my-scoold-app
heroku container:release web -a my-scoold-app
heroku config:set PARA_ENDPOINT=https://my-para.herokuapp.com -a my-scoold-app

DigitalOcean

1. Create a droplet running Ubuntu and SSH into it
2. Create a user ubuntu with adduser ubuntu
3. Execute the install script (as root):

   curl https://raw.githubusercontent.com/Erudika/scoold/master/installer.sh | bash

4. Copy the configuration file to your droplet:

   scp scoold-application.conf root@{droplet_ip}:/home/ubuntu

5. Restart Scoold:

   ssh root@{droplet_ip} "systemctl restart scoold.service"

6. Go to http://{droplet_ip}:8000 and verify that Scoold is running
7. Configure SSL on DigitalOcean or install nginx + letsencrypt on your droplet (see instructions below)

AWS

EC2 & Lightsail

1. Click the button, or open EC2 console
2. Choose a “Linux” AMI (e.g. “Ubuntu 24.04 LTS” or later)
3. Click “Add launch script” (user data) and copy the contents of installer.sh:
   installer.sh

   installer.sh

   #!/bin/bash
   set -e -x
   
   # Lightsail/DigitalOcean installer script for Ubuntu
   VERSION="1.66.0"
   PORT="8000"
   WORKDIR="/home/ubuntu"
   JARURL="https://github.com/Erudika/scoold/releases/download/${VERSION}/scoold-${VERSION}.jar"
   sfile="/etc/systemd/system/scoold.service"
   
   apt-get update && apt-get install -y wget openjdk-21-jre &&
   wget -O scoold.jar ${JARURL} && \
   mv scoold.jar $WORKDIR && \
   chown ubuntu:ubuntu ${WORKDIR}/scoold.jar && \
   chmod +x ${WORKDIR}/scoold.jar
   touch ${WORKDIR}/application.conf && \
   chown ubuntu:ubuntu ${WORKDIR}/application.conf
   
   # Feel free to modify the Scoold configuration here
   cat << EOF > ${WORKDIR}/application.conf
   scoold.app_name = "Scoold"
   scoold.port = 8000
   scoold.env = "production"
   scoold.host_url = "http://localhost:8000"
   scoold.para_endpoint = "https://paraio.com"
   scoold.para_access_key = "app:scoold"
   scoold.para_secret_key = ""
   scoold.admins = "admin@example.com"
   EOF
   
   touch $sfile
   cat << EOF > $sfile
   [Unit]
   Description=Scoold
   After=syslog.target
   StartLimitIntervalSec=30
   StartLimitBurst=2
   [Service]
   WorkingDirectory=${WORKDIR}
   SyslogIdentifier=Scoold
   ExecStart=java -jar -Dconfig.file=application.conf scoold.jar
   User=ubuntu
   Restart=on-failure
   RestartSec=1s
   [Install]
   WantedBy=multi-user.target
   EOF
   
   # This is optional. These rules might interfere with other web server configurations like nginx and certbot.
   #iptables -t nat -A PREROUTING -p tcp -m tcp --dport 80 -j REDIRECT --to-port ${PORT} && \
   #iptables -t nat -A OUTPUT -p tcp --dport 80 -o lo -j REDIRECT --to-port ${PORT}
   
   systemctl enable scoold.service && \
   systemctl start scoold.service

4. Download the default SSH key pair or upload your own
5. Choose the 512MB instance or larger (1GB recommended)
6. Wait for the instance to start and open the IP address in your browser at port 8000

Elatic Beanstalk

1. Clone this repo and change directory to it
2. Generate a WAR package with mvn -Pwar package
3. ↗ Create a new Beanstalk web app
4. Upload the WAR package target/scoold-x.y.z.war to Beanstalk, modify any additional options and hit “Create”

Authentication with Cognito

Scoold is fully compatible with Amazon Cognito because Cognito is just another OAuth 2.0 service provider. Here’s how to configure Scoold to work with Amazon Cognito:

1. Create a Cognito user pool (if you don’t have one already)
2. Create a Cognito App client with the OAuth 2.0 authorization code grant enabled:
3. Create a Cognito login subdomain for your app client (e.g.https://scoold.auth.eu-west-1.amazoncognito.com)
4. Add the new OAuth 2.0 authentication provider to your Scoold configuration:

   scoold-application.conf

   scoold.oa2_app_id = "cognito_app_client_id"
   scoold.oa2_secret = "cognito_app_client_secret"
   scoold.security.oauth.authz_url = "https://scoold.auth.eu-west-1.amazoncognito.com/login"
   scoold.security.oauth.token_url = "https://scoold.auth.eu-west-1.amazoncognito.com/oauth2/token"
   scoold.security.oauth.profile_url = "https://scoold.auth.eu-west-1.amazoncognito.com/oauth2/userInfo"
   scoold.security.oauth.provider = "Continue with Cognito"

5. Restart Scoold and login with a user from your Cognito user pool
6. Whitelist your Para auth endpoint with Cognito https://para_url/oauth2_auth as a valid redirect_uri.

Azure

1. Click the button to open Azure
2. Launch a new container by filling in the required parameters
3. Go to your container and press “Connect” using /bin/sh
4. In the terminal type in vi scoold-application.conf, hit i and paste in your configuration, hit Esc and type in :wq then restart your container OR, attach a secret volume to your container, containing the configuration. It should be mounted as /scoold/application.conf.

Azure Container Instances

az container create \
  --resource-group myResourceGroup \
  --name scoold \
  --image erudikaltd/scoold:latest \
  --dns-name-label my-scoold \
  --ports 8000 \
  --environment-variables \
    PARA_ENDPOINT=https://my-para.azurewebsites.net \
    PARA_ACCESS_KEY=app:scoold \
    PARA_SECRET_KEY=your-secret

Google App Engine

1. Download the Scoold JAR package to a local folder and rename it to scoold.jar
2. Copy the file app.gae.yaml from this repository to the same folder and rename it to app.yaml
3. Create a project in the Google Cloud Platform Console
4. Install the Google Cloud SDK
5. Edit app.gae.yaml and fill in the correct configuration properties
6. Deploy it with gcloud preview app deploy app.yaml

Google Cloud Run

gcloud run deploy scoold \
  --image erudikaltd/scoold:latest \
  --platform managed \
  --region us-central1 \
  --set-env-vars "PARA_ENDPOINT=https://para-xyz-uc.a.run.app,PARA_ACCESS_KEY=app:scoold,PARA_SECRET_KEY=secret" \
  --allow-unauthenticated \
  --port 8000

Servlet containers (Tomcat, Jetty, Undertow)

The instructions for Tomcat in particular are:

1. Generate a WAR package with: mvn -Pwar package
2. Rename the WAR package to ROOT.war if you want it deployed to the root context or leave it as is
3. Put the WAR package in Tomcat/webapps/ & start Tomcat
4. Copy config file

   cp scoold-application.conf Tomcat/webapps/scoold-folder/WEB-INF/classes/application.conf;
   ./catalina.sh stop
   ./catalina.sh start

Scoold is compatible with Tomcat, Jetty, Undertow and Payara.

Deploying Scoold under a specific context path

To deploy Scoold at a different path instead of the root path, set:

scoold-application.conf

scoold.context_path = "/newpath

The default value for this setting is blank, meaning Scoold will be deployed at the root directory.