Gleis documentation

Getting started

To deploy and manage your web app on Gleis, you will need to install the Gleis CLI on your computer and to create yourself an account.

Prerequisites

You will need the following, before you can install and use the Gleis CLI on your computer.

Ruby

In order to install the Gleis CLI gem, you will need to have the Ruby language installed on your computer.

To install Ruby on Linux and MacOS, you can use your system's package manager or you can use a Ruby manager, such as rbenv or RVM.

On Windows, the easiest way is to use the Ruby installer.

Git

You will also need the Git version control system, which you can install via your system's package manager on Linux and MacOS.

On Windows, you can download and install Git from the Git website. Make sure to choose the option "use Windows' default console window", during the installation process.

SSH

SSH can be installed via your system's package manager, if you have a computer running Linux or MacOS.

If you are a Windows user, then the Git installer from the previous step will have already installed SSH for you. You can use it via Git's bash shell or you can make it available to the Windows command line and Powershell, by adding the location of its executable to your PATH environment variable. To do this, you first need to know the location of the executable, by running:

Now copy this location and add it to the user's or system's environment variables.

Installing and using the Gleis CLI

1. To install the Gleis CLI gem, run the following command in your terminal: gem install gleis
2. Run the following command to see the available Gleis commands: gleis
3. To discover the parameters that can be passed to Gleis commands, run: gleis command_name -h

Get a Gleis account

1. You can get yourself a Gleis account directly via the Gleis CLI by running: gleis register name@company.ch We will take care of the rest.

Using Gleis for the first time

1. Log in to Gleis: gleis login name@company.ch
2. As soon as you are logged in for the first time, your Gleis SSH public/private key pair will be generated. The SSH key pair is used to authenticate you on the Gleis Git repository. If you already have a SSH key pair and wish to use that instead, you can do that too. To manage your SSH keys on Gleis, you can use the following commands: gleis auth key list|add|remove
3. Enter a strong passphrase for your new SSH key. This is an optional, but highly recommended, step.

Configuring Git

This guide assumes that you are using Git and that you have already initialised your web app as a Git project. At minimum, you have followed the steps below.

1. Configure your local Git author name and e-mail address, unless you are planning to use your global settings: git config user.name "First Last"
$ git config user.email name@company.ch
2. Initialise Git repository: git init
3. Commit to Git: git commit -am "commit message"

App deployment

Creating and deploying your web app on Gleis

1. Log in to Gleis: gleis login name@company.ch Type in your password, when prompted.
2. Inside your terminal, move to your web app's root directory: cd path/to/my_web_app
3. Create a new Gleis app. You can see the Gleis app as the environment, where your web application will be running. The following command will create a new Gleis app and, by default, it will give it the name of the current directory. You can specify a name by passing the "-a" parameter followed by the name of your choice. gleis app create
4. Deploy your web app by pushing it to the Gleis Git repository: git push gleis master

Re-deploying your web app after making modifications

1. Commit your changes to your local Git repository: git commit -am "my modifications"
2. Push to Gleis for re-deployment: git push gleis master

Deploying on Gleis directly from Travis CI

Deploying your web app directly from your Travis CI pipeline is supported and is as simple as adding the right configuration parameters to your project's .travis.yml file. Your web app will be automatically deployed to Gleis, upon a successful build in Travis CI.

1. First, generate an encrypted version of your Gleis password to be used with Travis CI: travis encrypt my_gleis_password
2. Add a new "deploy" block in your .travis.yml file with your username, app name and encrypted password from the previous step. deploy: provider: gleis username: my_email_address password: secure: "travis_encrypted_password" app: my_app_name
3. You can now push your changes to your GitHub repository and profit from automatic deployments to Gleis.

Maintenance mode

In case you need to carry out maintenance to your web app and would not like any users to access it during this time, you can turn on the maintenance mode, which will redirect all trafic to a standard page mentioning that your app is under maintenance.

For this purpose, turn on the maintenance mode:

Once finished, turn off the maintenance mode:

Web app health check

By default Gleis will perform a health check on your web app immediately at start-up. If you app is healthy, it will be made available online, through the gleis.app domain or the domain of your choice that you have defined. The health check works by issuing an HTTP GET request on the root ("/") of your web app. This means that your web app should return a HTTP 200 OK status code within 5 seconds on its root URL. If this is not the case, your app will not be made available online. While your app is running, a health check will be done every 20 seconds. Should your app not be in a healthy state, Gleis will automatically attempt to restart it for you.

Rolling back to a specific deployment

In case you need to go back to a previous version of your app, for example because something went wrong in the latest release, you will first need to find out the short commit hash of the deployment that you wish to revert to, by using:

Then use the 7-characters commit hash in the following command:

After a successful roll-back and, if you list again all of your app's deployments using the above command, you should see an asterisk (*) next to the app deployment that is currently being used.

Rebuilding your app image

In some rare cases, when for example the build of your app's image during a Git push to Gleis did not work properly or simply failed, you will want to force a re-build. In such situations, you can use the following command:

The result of the image build will appear at the end, as soon as it is finished, which usually takes a couple of minutes. Note that a successfull rebuild of your app's image does not automatically trigger a deployment or a restart of your app. You will need to manually stop and start your app, in order to use the newly built app image.

Restarting your app

If you need to restart your app, for example when you add new or make changes to existing environment variables, you can use the following command:

This will restart your app by using zero-downtime, meaning that your app will always be available. As an alternative, you can use the commands below, in order to stop and start your app. This, however, will lead to a short downtime.

Additional configuration options

Specifying a Ruby version

Gleis supports all stable and maintained Ruby versions. By default, we will use the latest stable Ruby version for your Ruby app's deployment. If your app requires a specific Ruby version, you can easily specify it in the .ruby-version file, which is found in the root directory of your app (you can create the .ruby-version file, if it doesn't already exist). The following two types of syntax are allowed in the .ruby-version file:

or:

Specifying a Node.js version

Gleis supports most Node.js versions that have an active or under-maintenance status. By default, the latest Node.js active LTS (long-term support) release will be used. If your app requires a specific Node.js version, you can specify this exact version number either in a file named ".nvmrc" in the root directory of your project, e.g. for version 12.18.3:

or directly inside your "package.json" file also in the root directory of your project, like this:

Note that, in both cases, you will need to use the exact version number, i.e. 12.18.3 and not 12 or 12.8.

Setting environment variables

Optionally, you can configure environment variables. In the following example, we are setting an environment variable that holds the key for an API.

Below, we are going to add the app's master key as an environment variable. This step is required in apps that are using the credentials.yml.enc file.

After adding, modifying or deleting an environment variable, you will need to restart your app, in order for it to take into account the change(s).

Using Databases in a Ruby on Rails project

1. Create a database: gleis db new
2. Promote a database; this will set this specific database as the app's default.
   Note: If you only have one database, then this will be automatically promoted and there is no need to run the following command. gleis db promote DATABASE1_URL
3. Install any pending Ruby on Rails migrations: gleis app exec "bundle exec rails db:migrate"
4. Optional: Seed a Ruby on Rails database: gleis app exec "bundle exec rails db:seed"

Using persistent storage

1. You can optionally add persistent storage for those files that are not checked out in the Git repository. Typically, these would be file uploads, such as photos, PDF files etc. gleis storage add dfs
2. You will need to attach the persistent storage to a specific directory. In the following example, we are mounting our persistent storage to a directory called "system", found inside our web app's "public" directory. gleis storage attach /usr/src/app/public/system

Adding a domain or subdomain to your app

By default, your web app all will automatically be available under a subdomain of gleis.app. If you would like to use your own domain or subdomain for your web app, you can do so with the following command:

Note that for this to work, you will first need to point the DNS entry/entries of your domain, at your domain registrar or DNS provider, to the gleis.app DNS name of your web app, using a CNAME DNS record. For example:

If you do not want a www entry, you can simply omit it.

For an overview of the DNS names, under which your app is available, you can use the following command:

Finally, if you would like to remove a DNS name from your app, use the following command:

Scheduled jobs

If your app requires a command to be run on a regular basis, e.g. hourly or daily, you can add it to the Gleis scheduled jobs. For example, in order to run the "bundle exec rails search:index" job every day at 22:00, you would want to use the following command:

You can then list the scheduled jobs for your app using:

To remove the scheduled job:

Note that only one scheduled job per app is currently possible. Contact us, if your app requires more than one scheduled job.

The Procfile file

When deploying an app, Gleis automatically detects the technology stack behind and chooses the appropriate command to run your web app (e.g. "bundle exec rails server" for Ruby on Rails or "npm start" for Node.js). In some cases you will want to override this start-up command. This is the purpose of the Procfile file. To do so, create a file with the name Procfile, in the root directory of your project, and specify the command to run after the process type "web" label. In the following example we are specifying the command that runs the Ruby Rack web server:

After adding the Procfile, commit your changes and push your app to Gleis. You should see the new start-up command in the output here:

Reference

Standard port numbers

Depending on which technology stack you are using, you will need your web app to listen on a specific and standard port number, in order to make it available on the Internet. Here is a list of these port numbers by technology stack: