This guide will help you setup Runnable templates for a simple 2-tier Node.js application. This guide will assume that you don't have a Dockerfile and want Runnable to generate the Dockerfile for you using a simple setup guide.
Configuring the App
- Choose your GitHub org.
- On the Configure page, click on the Create Template button.
- Find the repository you would like to configure the template for. In this case, we are starting with a simple Python repository.
- Choose the first option to use our simple setup guide.
- Give your template a name. This name will be used to generate the template URLs of all the containers that will launch from this template. Check out this article for more details on URLs in Runnable.
- Next, you’ll be able to select your app’s Stack Type, Version and Branch for your template. Go ahead and choose Node.js for your stack type, and select the version you want to use. Make sure you choose the branch that corresponds to your team’s main integration branch (‘master’ or ‘develop’ for example).
- On the next step, you can specify additional Packages, Build Commands, and the Container CMD.
This option allows you to install any tools, libraries, or frameworks you need. Add multiple packages by separating them with spaces. You can specify packages that are listed in the Ubuntu Aptitude library.
For our simple API repository, this is where we’ll specify "npm install".
Note: Build commands cannot connect to any other container during a build. It is therefore not recommended to seed databases or communicate with another container using the Build Commands.
Here the main run command for your app is specified. Important: the container will stop running when this command exits. For our simple API repository, we will specify "npm start".
NOTE: Commands that run here will have network access to other Runnable containers. TIP: use "&&" to run multiple commands; for example, to run a migration on your database and start your app, you can specify "npm run migrations && npm start"
- Click Next. Additional configuration options are revealed to customize your container further:
Add any required Environtment Variables your app may need. These values will be inserted into a container's environment when it launches from the template. The the syntax for entering in Environment variables is KEY=VAL i.e. if you are trying to set the "CONFIG" to "DEV", you would input "CONFIG=DEV".
Files & SSH Keys
Use this tool to add any addtional configuration files, other GitHub repositories, SSH Keys or assets your repository needs to build and run properly. This is also the option to use if you have to upload any override files to overwrite any hard coded values in your repository.
For more details, Check Out:
Open up any ports your repository may need.
Our simple API repository only needs port "3000" to be open.
- Once you are happy with Save & Build to save our changes and trigger your first build.
- You will be automatically transitioned to the Logs tab of your configuration. Here you will be able to access:
These logs correspond to all the output from the build process of your template. Any errors here will correspond to configuration options you have specified in your repository, Build Commands, Packages and Files & SSH keys.
These logs correspond to all the output from the run process of a container launched from your template. Any errors here will correspond to configuration options you have specified in your CMD Command or Environment Variables.
NOTE: Your repository can crash for several reasons outside of your configuration on Runnable. There could be several factors ranging from a bug in your code or a misconfigured connection.
This is a terminal session into a container launched from your template. This is useful to verify any configuration details you may want to confirm.
This is the Environment URL corresponding to the container launched from the default branch. Check this article out for more about Runnable URLs.
- If everything went well, your build will complete successfully. Anytime you run across an error that you need help with, we have developers ready to help in real-time. Click on the chat bubble on the bottom left!
Connecting to a DB template
In our case, we added a MySQL template.
Our repository is setup to use the environment variable "MYSQL_HOST" to reference the hostname for MYSQL. To connect our "api" repository template to the "MySQL" template, open up the "Environment Variables" tool in the "api" template configuration modal.
Note: If you don't use Environment Variables for host discovery, you may have to modify your repository to use the Runnable template URL as your MySQL hostname. You can do this by either uploading a file using "Files & SSH Keys" or by actually modifying your repository on Github.com.
Specify the the value for the "MYSQL_HOST" environment variable. From our article Runnable URLs, it is clear that we need to use MySQL's template URL to connect to it. As a convenience we provide all template URLs in the Environment Variables tab.
Click Save & Build.
The "api" template is now successfully connected with the "MySQL" template!
Head on over to our Branches section to see how to containers from your templates.