+ Swiss PaaS +

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:

where ssh

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.

Configure 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

Create and deploy 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.

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:

2.6.6

or:

ruby-2.6.6

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.

gleis app config API_KEY=my_api_key

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