👋 Hello Nais ¶

This tutorial will take you through the process of getting a simple application up and running on Nais.

Prerequisites ¶

⚙️ Setup ¶

Create your own GitHub repository ¶

Create your own repo using the nais/hello-nais as a template.

You create a new repository through either the GitHub UI or through the GitHub CLI:

gh repo create <GITHUB-ORG>/<MY-APP> --template nais/hello-nais --private --clone

cd <MY-APP>

Authorize the repository for deployment ¶

This is required for the GitHub Actions workflow to be able to deploy your application.

Visit Nais Console. Select your team, and visit the Repositories tab.

Here you can add your repository to the list of authorized repositories. This authorizes the GitHub repository to perform deployments on behalf of your team.

Dockerfile ¶

This describes the system your application will be running on. It includes the base image, and the commands needed to build your application. This is the payload you are requesting Nais to run. We have created this file for you, as there are no changes needed for this tutorial. Check it out.

Application manifest ¶

This file describes your application to the Nais platform so that it can run it correctly and provision the resources it needs.

Create a file called app.yaml in a .nais-folder.

mkdir .nais
touch .nais/app.yaml

Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines:

apiVersion: nais.io/v1alpha1
kind: Application
metadata:
  name: <MY-APP>
  namespace: <MY-TEAM>
spec:
  ingresses:
    - https://<MY-APP>.<MY-ENV>.nav.cloud.nais.io
  image: {{image}}1
  port: 8080
  ttl: 3h
  replicas:
    max: 1
    min: 1
  resources:
    requests:
      cpu: 50m
      memory: 32Mi

GitHub Actions workflow ¶

GitHub Actions uses the Dockerfile from step 1 and the app.yaml from step 2. to build and deploy your application to Nais.

Create a file called main.yaml in a .github/workflows-folder.

mkdir -p .github/workflows
touch .github/workflows/main.yaml

Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines:

name: Build and deploy
on:
  push:
    branches:
      - main
jobs:
  build_and_deploy:
    name: Build, push and deploy
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v4
      - name: Build and push image and SBOM to OCI registry
        uses: nais/docker-build-push@v0
        id: docker-build-push
        with:
          team: <MY-TEAM> # Replace
      - name: Deploy to Nais
        uses: nais/deploy/actions/deploy@v2
        env:
          CLUSTER: <MY_ENV> # Replace1
          RESOURCE: .nais/app.yaml # This points to the file we created in the previous step
          VAR: image=${{ steps.docker-build-push.outputs.image }}2
          TELEMETRY: ${{ steps.docker-build-push.outputs.telemetry }}

Excellent! We're now ready to deploy 🚀

🚢 Ship it ¶

Previously we've made our application and created the required files for deployment. In this part of the tutorial we will deploy our application to Nais.

Commit and push your changes ¶

Now that we have added the required files, it's time to commit and push them to GitHub.

git add .
git commit -m "FEAT: Add nais app manifest and github workflow"
git push origin main

Observe the GitHub Actions workflow ¶

When pushed, the GitHub Actions workflow will automatically start. You can observe the workflow by running the following command:

gh run watch

If you get a 403 PERMISSION_DENIED error in the Build and push image step, you might not have added your repo to the Nais team as described above, or it might not have synchronized yet.

Visit your application ¶

On successful completion, we can view our application at https://<MY-APP>.<MY-ENV>.nav.cloud.nais.io

Congratulations! You have now successfully deployed your first application to Nais! The next and most important step is to clean up after ourselves.

🧹 Clean up ¶

During this tutorial we have

Now it's time to clean up after ourselves.

Delete your repository ¶

When you are finished with this guide you can delete your repository:

gh repo delete <GITHUB-ORG>/<MY-APP>

Your next application ¶

In this guide, we took a few short-cuts to get you up and running quickly.

For instance, we didn't explore all the possibilities of the app.yaml file, or take advantage of the integrations the nais platform provides. To learn more about the possibilities, explore our documentation for Applications and Nais Jobs.

The GitHub workflow is similarly simplified. Some teams like to do more advanced things, like running tests, or deploying to multiple environments. It is also possible to skip some steps under certain conditions, such as not building a new image if the code hasn't changed. Explore the GitHub Actions documentation for more information about GitHub Actions in general, and our guide on workload image for how you can skip building.