DevOps

Managing your Scoold server

Maintaining your Scoold server is relatively easy because it does not store any data locally, apart from logs in scoold.log. Scoold Pro may store uploaded files locally inside the ./uploads folder. That folder is automatically added to the backup archive when a new backup is requested. All data is stored in the Para backend, inside the configured database of choice.

The backend, Para, is also easy to maintain and is designed to be a “set-it-and-forget-it” kind of service. It is only important to keep it up to date for security patches and minor fixes.

Backup & Restore

From the Administration page in Scoold, go to the Backup & Restore section and create a new backup. The backup file is prepared in the background and will be downloaded to disk. It contains all the data for your Scoold instance.

When you wish to restore a data archive, upload the zip file to Scoold and click “Restore”. Optionally, specify whether you want the existing data to be overwritten with the data from the backup file.

Upgrading Scoold to a new version

The upgrade process is straightforward:

1. Stop the Scoold server
2. Download a new version and replace the old JAR package with the newer version.
3. Start Scoold again

If using Docker do this:

# check for and if available pull a new image
docker compose pull
docker compose up -d

Upgrading from Scoold to Scoold Pro

You can seamlessly upgrade from Scoold to Scoold Pro without changing the configuration or anything else in your infrastructure. The process is very simple:

1. Get your Scoold Pro package (JAR or WAR)
2. Stop (undeploy) Scoold and replace its package with the Scoold Pro package
3. Start Scoold Pro (or redeploy your Scoold Pro WAR file)

If using Docker, and you have access to the private Docker registry for Scoold Pro, do this:

# access the private registry first
docker login --username AWS --password-stdin \
    374874639893.dkr.ecr.eu-west-1.amazonaws.com
# check for and if available pull a new image
docker pull 374874639893.dkr.ecr.eu-west-1.amazonaws.com/scoold-pro:latest_stable
# start Scoold Pro
docker run -ti -p 8000:8000 374874639893.dkr.ecr.eu-west-1.amazonaws.com/scoold-pro:latest_stable

Read the Docker guide for Scoold Pro How to get started with Scoold Pro containers and how to access the private registry.

Migrating from Stack Overflow for Teams (Business) to Scoold

1. Start Scoold and login as admin
2. Download your data archive from Stack Overflow by browsing to Admin settings > Account info > Download data
3. On Scoold’s Administration page click Import and select the Stack Overflow archive (.zip)
4. Check This archive was exported from Stack Overflow and click import

All the data for your team on Stack Overflow, except for user badges, will be imported into Scoold.

Migrating from one Para deployment to another

There are situations where you want to transfer your data from one Para server to another. This may be because you decided to switch databases or hosting providers. This process is made simple with the backup and restore feature in Scoold and Scoold Pro. Simply go to the Administration page and download all your data from the source installation. Then on the target installation go to the Administration page and import the ZIP file which contains the backup.

Important

All data will be overwritten on restore, so it’s highly recommended that the target Scoold installation is fresh and contains no data.

When using the default H2 database, you can also copy the ./data directory to the new installation or just copy all *.db files. The data directory also contains Lucene index folders for each app, e.g. ./data/scoold-lucene. These folders can also be moved and copied or even deleted. You can easily restore the Lucene index for a Para app by running a rebuild index task from the para-cli tool. Here’s how to rebuild the root app para and a child app scoold with just two simple commands:

npm i -g para-cli
para-cli setup

para-cli rebuild-index --endpoint "http://localhost:8080" \
    --accessKey "app:para" --secretKey "secret1"

para-cli rebuild-index --endpoint "http://localhost:8080" \
    --accessKey "app:scoold" --secretKey "secret2"

Self-hosting Para and Scoold with HTTPS

The recommended way for enabling HTTPS with your own SSL certificate in a self-hosted environment is to run a proxy server like NGINX in front of Scoold and Para. As an alternative you can use Apache or Lighttpd.

1. Start Para on port :8080
2. Start Scoold on port :8000
3. Start NGINX with the configuration below

Example configuration for NGINX

/etc/nginx/nginx.conf

server_tokens off;
add_header X-XSS-Protection "1; mode=block";
add_header X-Content-Type-Options nosniff;

server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name www.domain.com domain.com;

    # Redirect all HTTP requests to HTTPS with a 301 Moved Permanently response.
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name www.domain.com domain.com;

    # certs sent to the client in SERVER HELLO are concatenated in ssl_certificate
    ssl_certificate /etc/ssl/certs/domain.crt;
    ssl_certificate_key /etc/ssl/private/domain.key;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_session_tickets off;

    # modern configuration. tweak to your needs.
    ssl_protocols TLSv1.2;
    ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256';
    ssl_prefer_server_ciphers on;

    # HSTS (ngx_http_headers_module is required) (15768000 seconds = 6 months)
    add_header Strict-Transport-Security max-age=15768000;

    # OCSP Stapling - fetch OCSP records from URL in ssl_certificate and cache them
    ssl_stapling on;
    ssl_stapling_verify on;

    # Verify chain of trust of OCSP response using Root CA and Intermediate certs
    #ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;

    # Cloudflare DNS
    resolver 1.1.1.1;

    # Required for LE certificate enrollment using certbot
    # usually certbot would automatically modify this configuration
    #location '/.well-known/acme-challenge' {
    #  default_type "text/plain";
    #  root /var/www/html;
    #}

    location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_redirect http:// $scheme://;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header Host $http_host;
    }
}

As an alternative, you can enable SSL and HTTP2 directly in Scoold:

1. Run the script ↗ gencerts.sh to generate the required self-signed certificates

   echo "scoold.local" | sudo tee -a /etc/hosts
   ./gencerts.sh scoold.local secret

   The result of that command will be 8 files - ScooldRootCA.(crt,key,pem), scoold.local.(crt,key,pem) as well as a Java Keystore file scoold-keystore.p12 and a Truststore file scoold-truststore.p12. Optionally, you can run generate the server certificates using an existing RootCA.pem and RootCA.key files like so:

   ./gencerts.sh para.local secret /path/to/ca/RootCA

2. Run Scoold using the following command which enables SSL and HTTP2:

   java -jar -Dconfig.file=./scoold-application.conf \
    -Dserver.ssl.key-store-type=PKCS12 \
    -Dserver.ssl.key-store=scoold-keystore.p12 \
    -Dserver.ssl.key-store-password=secret \
    -Dserver.ssl.key-password=secret \
    -Dserver.ssl.key-alias=scoold \
    -Dserver.ssl.enabled=true \
    -Dserver.http2.enabled=true \
   scoold-*.jar

3. Trust the root CA file ScooldRootCA.crt by importing it in you OS keyring or browser (check Google for instructions).

4. Open https://scoold.local:8000

Securing Scoold with TLS using Nginx and Certbot (Let’s Encrypt)

First of all, configure the DNS records for your domain to point to the IP address where Scoold is hosted.

1. SSH into your Ubuntu server and install Nginx and Certbot

   sudo apt-get install nginx certbot python-certbot-nginx

2. Get a certificate and autoconfigure nginx to use it

   sudo certbot --nginx

3. Turn on the Ubuntu firewall to block port 8000 and only allow ports 80 and 443.

   ufw allow 'Nginx Full' && sudo ufw enable

4. Configure nginx to forward requests from the web on ports 80 and 443 to localhost:8000

   location / {
     proxy_pass http://127.0.0.1:8000;
     proxy_redirect http:// $scheme://;
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto https;
     proxy_set_header Host $http_host;
   }

That’s it! If the Certbot validation above fails, your DNS is not configured properly or you have conflicting firewall rules.

Mutual TLS authentication

You can enable mTLS between Scoold and Para, as well as between Scoold and a proxy like Nginx. There are two ways to do that:

• each service can trust each other’s public certificate
• each service can use a TLS certificate signed by a CA which is trusted by all services

mTLS between Scoold and an TLS-terminating Nginx proxy

To go the first route, execute the getcerts.sh script as shown above. You may need to run it once for Scoold and once for Nginx, unless Nginx has its own certificate already. Then add the Nginx certificate to the Truststore.

./gencerts.sh scoold.local secret
keytool -v -importcert -file /path/to/nginx_public_cert.pem -alias nginx -keystore scoold-nginx-truststore.p12 -storepass secret -noprompt

Configure Nginx to trust the CA which was used to sign Scoold’s server certificate:

server_name scoold-pro.local;
listen 443 ssl http2;
location / {
  proxy_pass https://scoold.local:8000;
  proxy_redirect http:// $scheme://;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto https;
  proxy_set_header Host $http_host;

  proxy_ssl_certificate /path/to/nginx_public_cert.pem;
  proxy_ssl_certificate_key /path/to/nginx_public_cert.key;
  proxy_ssl_trusted_certificate /path/to/RootCA.pem;
  proxy_ssl_verify on;
  proxy_ssl_verify_depth 2;
}

Run Scoold with this command which enables TLS, HTTP2 and mTLS.

java -jar -Dconfig.file=./scoold-application.conf \
    -Dserver.ssl.key-store-type=PKCS12 \
    -Dserver.ssl.key-store=scoold-keystore.p12 \
    -Dserver.ssl.key-store-password=secret \
    -Dserver.ssl.key-password=secret \
    -Dserver.ssl.trust-store=scoold-nginx-truststore.p12 \
    -Dserver.ssl.trust-store-password=secret \
    -Dserver.ssl.key-alias=scoold \
    -Dserver.ssl.client-auth=need \
    -Dserver.ssl.enabled=true \
    -Dserver.http2.enabled=true
    scoold-*.jar

If you want to trust the Root CA instead, the steps are similar but in the Nginx configuration use this line:

ssl_client_certificate /path/to/RootCA.pem;

And start Scoold using the previously generated Truststore scoold-truststore.p12 which should already contain the Root CA.

mTLS between Scoold and Para

To go the first route, execute the getcerts.sh script as shown above for both Scoold and Para. Then create a Truststore for each service which contains the certificate of the other.

./gencerts.sh scoold.local secret
./gencerts.sh para.local secret
keytool -v -importcert -file scoold.local.pem -alias scoold -keystore para-scoold-truststore.p12 -storepass secret -noprompt
keytool -v -importcert -file para.local.pem -alias para -keystore scoold-para-truststore.p12 -storepass secret -noprompt

Run Para with this command which enables TLS, HTTP2 and mTLS.

java -jar -Dconfig.file=/para/para-application.conf \
    -Dserver.ssl.key-store-type=PKCS12 \
    -Dserver.ssl.key-store=para-keystore.p12 \
    -Dserver.ssl.key-store-password=secret \
    -Dserver.ssl.key-password=secret \
    -Dserver.ssl.trust-store=para-scoold-truststore.p12 \
    -Dserver.ssl.trust-store-password=secret \
    -Dserver.ssl.key-alias=para \
    -Dserver.ssl.client-auth=need \
    -Dserver.ssl.enabled=true \
    -Dserver.http2.enabled=true
    para-*.jar

Run Scoold with this command which enables TLS, HTTP2 and mTLS.

java -jar -Dconfig.file=/scoold/scoold-application.conf \
    -Dserver.ssl.key-store-type=PKCS12 \
    -Dserver.ssl.key-store=scoold-keystore.p12 \
    -Dserver.ssl.key-store-password=secret \
    -Dserver.ssl.key-password=secret \
    -Dpara.client.ssl_keystore=scoold-keystore.p12 \
    -Dpara.client.ssl_keystore_password=secret \
    -Dpara.client.ssl_truststore=scoold-para-truststore.p12 \
    -Dpara.client.ssl_truststore_password=secret \
    -Dserver.ssl.key-alias=scoold \
    -Dserver.ssl.enabled=true \
    -Dserver.http2.enabled=true
    scoold-*.jar

If you want to trust the Root CA instead, the steps are similar but using the previously generated Truststores

• scoold-truststore.p12 and para-truststore.p12 respectively, which should already contain the Root CA.

For end-to-end encryption of traffic, you can enable mTLS between your TLS-terminating proxy (like nginx), Scoold and Para.

Complex proxy server scenarios

In some rare cases, your Scoold server may be behind more than one proxy servers. In these cases you have configuration like this:

scoold-application.conf

scoold.host_url = "http://192.168.3.4:8000"
scoold.host_url = "http://192.168.3.4:8080"

This would work except for transactional emails where inbound links point to the wrong address. The solution is to add this to your configuration:

scoold-application.conf

scoold.rewrite_inbound_links_with_fqdn = "https://public-scoold-domain.com"