Get started with Walhall

In this tutorial, you will deploy your first containerized app on Walhall.

Before you start

GitHub organization account

You need a GitHub account that is part of a GitHub organization that has been linked to Walhall.

If your organization has already been linked to Walhall, then go to the registration form and register with your GitHub account. You will then have access to your organization’s apps on Walhall.

Repository requirements

If you want to deploy your own repositories in your first app, then you must make sure that they meet the following requirements.

We offer a sample repository that you can use if you just want to get something simple up and running.

Drone file

Each repository must have a Drone file (.drone.yml) in its root. You can copy and paste these contents into the file without having to change anything:

# .drone.yml - Sample file for connecting your module to Walhall's CI/CD pipeline. 
# Save this in the repository root. You don't have to change anything.
# All environment variables are created in Walhall as secrets.

pipeline:
# Walhall requires git tags to exactly match the image tags. 
# This step preserves the tags.
  preserve-git-tags:
    image: bash
    commands:
      # If the commit reference is a tag, then Drone will write the tag to the .tags file
      - bash -c "[[ \"${DRONE_COMMIT_REF}\" == \"refs/tags/\"* ]] && echo \"${DRONE_COMMIT_REF#refs/tags/}\" > .tags"
    when:
      event: [tag]

  # This step builds the module's Docker image and pushes it to the registry when a tag is pushed.
  # Drone is configured to use the Walhall registry by default.
  build-docker-image-tag:
    image: plugins/docker
    registry:
      from_secret: DOCKER_REGISTRY
    repo:
      from_secret: DOCKER_REPO
    username:
      from_secret: DOCKER_USERNAME
    password:
      from_secret: DOCKER_PASSWORD
    insecure: true
    file: Dockerfile
    when:
      event: [tag]
      status: [success]

See the Drone page for more information.

Dockerfile

Each repository must include a Dockerfile that builds an image of the code.

Please note the port used to serve your code.

Git tag

Your repository must have a tagged commit that includes the Drone file and the Dockerfile.

In GitHub, you can create this by going to your repository, clicking on Releases, and then clicking on Draft new release.

Use our sample repositories

We have a sample frontend and backend that can be deployed with Walhall:

You will have to do a tiny bit of configuration for the frontend in steps 3 and 4.

Go to the repositories, fork them to your organization’s account, and then push a tag in each.

1. Build the app

  1. Log in to Walhall.
  2. Enter a name for your new app and click Create.
  3. Now you will see a list of repositories that have been imported from your organization into Walhall. In Walhall, these are known as modules.
    Click the Sync repositories button. When the list has been refreshed, click the Add button next to each module you want to include in the app.
    Screenshot: List of modules while creating an app
    Can’t see your repositories? See the Troubleshooting page for more information.
  4. When you’re ready, click Review.

Now, Walhall will create your app and build the images of your modules.

The next screen that loads will display the development environment of your app. Each environment contains a set of configurations for the modules in the app, including module versions and configuration/environment variables.

Click here to read more about modules and how to add them to your app.

2. Create deployment draft

When you want to make changes to your deployment environment, you create a deployment draft to preview changes before they go live.

Click the Create Draft button to the right of the modules list:

Screenshot: Create deployment draft

3. Expose modules with public URLs

If you intend for your modules to be accessed from outside the cluster (e.g., with a web UI or an API), then you must expose those modules with a public IP address. To do so:

  1. Click on the module you want to expose.
  2. The module configuration screen will load. In the Custom port mapping section, check the box labeled Expose with public URL.
    Screenshot: Expose public URL
  3. Enter the port where your module exposes its content in the container port field.
  4. Click Close to return to the app overview screen.

4. Environment variables

If your modules rely on environment variables, then you can define them in the Variables section of the module configuration screen.

You can create variable substitutions that resolve to properties of other modules or databases. See the environment variables for more information.

If you’re using the product-fe and product-be repositories, then go to the product-fe configuration screen, scroll down to the Variables section, and add the following environment variable:

PRODUCT_BE_SERVER_URL: https://${modules.product-be.service.name}/products

5. Deploy the app

Click the Deploy to Development button to the right of the modules list.

A modal will appear with a list of the changes that will be deployed. Click the Deploy button to trigger the process.

When your app finishes deploying, the Development environment will be tagged as “Running” in the upper right corner. A public URL will show on each module that you exposed:

Screenshot: 2048 URL

That’s it! Click the URL to access your module.

Click here to read more about the deployment process.

Further development

This tutorial showed you how to get a simple app up and running in a Kubernetes cluster managed by Walhall. We recommend reading our documentation on:

Free trial limitations

The following limitations apply to the free trial of the Humanitec platform:

  • Both user access management and source code management are handled through GitHub.
  • You may create no more than 20 apps, with no more than 3 environments each.
    • If you deploy your app to a cluster managed by Humanitec, then each deployed module will have a lifespan of 1 day.
  • You may only create development environments with the free trial.
  • The free trial does not include the role-based access control model. Each member of an organization in Walhall has full access to all applications for that organization and can delete and edit environments and applications.
  • Your app must implement Walhall’s CI/CD pipeline, i.e., using a Drone file.
  • For ingress, all deployed modules must use the *.newapp.io certificate.