Stratum Initial Setup

This article is intended to get you up and running on your new Stratum environment. If you’d like to read more, please look through the rest of the Getting Started guides.

If you don’t yet have an environment, or you have questions on Stratum’s capabilities and offerings, please get in touch.

1. Access

Once your new environment has been provisioned and is ready to use, you will receive two emails. The first is simply a notification that it’s ready, which you will receive for every environment. This contains your environment’s public hostname - take note of this for later. The second is an invitation to join the new organization that has been created for you - this will only be sent for the very first environment that we provision for you. The invitation email contains a link to the Stratum dashboard - click it!

The Stratum dashboard will prompt you to sign in with your Catalyze account - if you don’t have one already, you can also create one at this point - just follow the instructions on the page. After signing in (or creating a new account, verifying your email address, then signing in), click the “Stratum” link from the product list. You should see your organization in the upper-right corner:

org corner

For more on managing organizations, including how to add additional members and grant them access to your environment, see the Managing Organizations article.

Note: Occasionally, if interrupted while creating an account, you might find that your invite did not get accepted, and you are not a member of your organization yet. If this happens, just click the link in your email again.

Once you’ve confirmed that you’re a member of your organization, you should also see your environment’s summary listed in the Stratum dashboard, looking something like this:

org summary

From the summary, note your environment’s name and your code service’s name - in the above image, those are “MyEnvironment-production” and “app01”, respectively.

2. Install the Catalyze CLI

Catalyze provides a CLI (command-line interface) tool to facilitate interaction with your Stratum environment, supporting Windows, OSX, and Linux.

To install the CLI, follow the instructions in its Github repository.

3. Add Your Public Key

In order to push code, Catalyze needs to have a public key attached to your account. If you don’t have one yet, you can create one via the following on OSX/Linux:

ssh-keygen -t rsa -b 4096 -C ""

To add your key to your account, use the keys add command, which has the form catalyze keys add <key name> <path to key>. For example, if you want to call your key “my-catalyze-key” and the path to it is ~/.ssh/, the command you would run would be:

catalyze keys add my-catalyze-key ~/.ssh/

This will prompt you to sign in with your Catalyze account. You can then validate that the key was added using catalyze keys list.

4. Associate to Your Environment

Note: If your environment has more than one code service, this step and all steps after will need to be repeated for each one.

In order for the CLI to know which environment it should be interacting with (and, coincidentally, who you are), you first need to associate your local code repo to your new environment. “Associating” does the following:

  1. Find the internal identifiers for your environment and code service, and cache those locally.
  2. Set the catalyze Git remote.

The form of this command in the CLI is: catalyze associate <environment name> <code service name>. For the example from Step 1, that would be catalyze associate MyEnvironment-production app01.

For options for the associate command, see the CLI reference.

5. Upload Your SSL Certificate

Acquiring SSL certs is a very complex topic - if you’d like to read more information than what is outlined below, please see the SSL Certificates article. The certificate and private key must be unencrypted and in PEM format.

Note: This can be a wildcard cert. Wildcard certs can be reused.

The CLI command to upload a cert is certs create, taking the form catalyze certs create <cert name> <path to crt file> <path to key file>. For example:

catalyze -E "<your_env_alias>" certs create

If that cert is self-signed, pass the -s option:

catalyze -E "<your_env_alias>" certs create -s

Note: Using a self-signed cert can be very useful for development or staging environments.

For wildcard certs, the typical nomenclature is *.domain.tld:

catalyze -E "<your_env_alias>" certs create *

6. Set Your DNS

Because an environment can have any number of code services, the public hostname for the environment does not point to any of them. What this means is that, in order to access each code service in your application, you will need to set up DNS that will forward to it. This step is executed entirely outside of Stratum - Catalyze cannot do any step of this for you. Catalyze is not a DNS provider.

First, choose the hostname you would like to use for the code service - this can be either an apex domain (such as or a subdomain (such as

Then, in your DNS provider’s control panel, set up a CNAME from that hostname to your environment’s public hostname (ALIAS can be used if CNAME is not supported by your provider). We recommend setting a TTL of 300s.

To verify that your DNS change has propagated (which typically takes a few minutes), use nslookup:

$ nslookup
Non-authoritative answer: canonical name =

Note: Some DNS providers may not allow CNAME or ALIAS records for apex domains. If you discover that your host has this limitation and using a subdomain is not an option, we recommend transferring your domain over to Cloudflare.

7. Set Up a Site

Stratum uses what we call Sites to map code services to hostnames, using the cert that was uploaded in step 5.

The CLI command to create a cert is sites create, taking the form catalyze sites create <hostname> <code service name> <cert name>. For example, using the hostname from step 6, the wildcard cert name from step 5, and the code service name noted in step 1:

catalyze -E "<your_env_alias>" sites create app01 *

This will generate a new nginx configuration file for the new site.

8. Redeploy the Service Proxy

In order to pick up on the new site file, your environment’s Service Proxy needs be redeployed. This is done via the redeploy command:

catalyze -E "<your_env_alias>" redeploy service_proxy

After a short period of downtime (usually 20-40 seconds), your service proxy will be responding again. If your site, certs, and DNS are set up correctly, navigating to the hostname in the site you just configured ( in the example above) should result in a 503 error.

Once you have an SSL certificate added to an environment and the DNS name you want to resolve pointed at your POD URL, you’ll need to create a site for the environment that uses the certificate and listens for that DNS name. Until you create a site, you will not be able to route traffic to your application.

You can verify that your certificate is correctly being used with openssl:

openssl s_client -connect

9. Push Code

In order to build an image for your code service’s container to run, you do a git push to the catalyze remote, pushing the master branch:

git push catalyze master

Note: The pushed branch must be master. If the branch you want to push is not master, use the following:

git push catalyze mybranchname:master

After your push, you will see build output stream to your terminal window. Any build error output will be there. For related information, read the Writing Your Application article.

After your build succeeds, a deploy job will be started for it. Shortly after (20-40 seconds, plus however long it takes your application to start up and respond). After that, your application should be available at the hostname you configured in the site. Congratulations!

Note: If your application builds successfully but is not behaving as expected, read through the Writing Your Application to Work With Stratum article.

If your application includes workers, use the worker command to start them (you only need to do this the first time):

catalyze -E "<your_env_alias>" worker deploy <service_name> <target>

Where target is the name of the Procfile target to be run (typically “worker”).

See also

Cloud computing for healthcare

If you store, process, or transmit Protected Health Information, rely on Catalyze to keep you HIPAA compliant with our platform as a service, mobile backend, or managed HL7 integrations.

Contact Us Learn More

Catalyze learning resources

Learn the important and intracate details of HIPAA compliance, make use of HL7, and understand the security aspects of handling protected health information with our learning resources.

Visit Catalyze Learning Resources