# 👋 Hello Nais

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

## Prerequisites

- You have a GitHub account connected to your GitHub organization (e.g. `navikt`)
- [Member of a Nais team](/explanations/team.md)
- [GitHub CLI installed](https://cli.github.com/)
- [Nais CLI](https://cli.nais.io) installed and authenticated (for the restart step)

> **Conventions**
> Throughout this guide, we will use the following conventions:

> - `<MY-APP>` - The name of your Nais application (e.g. `joannas-first`)
> - `<MY-TEAM>` - The name of your Nais team (e.g. `onboarding`)
> - `<GITHUB-ORG>` - Your GitHub organization (e.g. `navikt`)
> - `<MY-ENV>` - The name of the environment you want to deploy to (see [environments](/workloads/reference/environments.md))

> **NB!** Choose names with *lowercase* letters, numbers and dashes only.

## ⚙️ Setup

### Create your own GitHub repository

Create your own repo using [nais/hello](https://github.com/nais/hello) as a template.

You create a new repository through either the [GitHub UI](https://github.com/new?template_name=hello&template_owner=nais) or through the GitHub CLI:

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

```bash
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](https://console.dev-nais.cloud.nais.io). 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. Have a quick look to get familiar.

### 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.

```bash
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:

> **.nais/app.yaml**
> ```yaml
> apiVersion: nais.io/v1alpha1
> kind: Application
> metadata:
>   name: <MY-APP>
> spec:
>   ingresses:
>     - https://<MY-APP>.<MY-ENV>.dev-nais.cloud.nais.io
>   port: 8080
>   ttl: 3h # Time before clean-up (1)
>   replicas:
>     max: 1
>     min: 1
>   resources:
>     requests:
>       cpu: 50m
>       memory: 32Mi
> ```

> 1. This sets the ["time to live"](/workloads/application/reference/spec.md#ttl) for your app to 3 hours, in case you start on this tutorial and forget to clean up after.

The deploy workflow selects the team. You do not need to set a namespace in the manifest.

### 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.

```bash
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:

> **.github/workflows/main.yaml**
> ```yaml
> name: Build and deploy
> on:
>   push:
>     branches:
>       - main
> jobs:
>   build:
>     name: Build and push image
>     runs-on: ubuntu-latest
>     permissions:
>       contents: read
>       id-token: write
>     outputs:
>       image: ${{ steps.docker-build-push.outputs.image }}
>     steps:
>       - uses: actions/checkout@v6 # Should be pinned (1)
>       - name: Build and push image and SBOM to OCI registry
>         uses: nais/docker-build-push@v0 # Should be pinned
>         id: docker-build-push
>         with:
>           team: <MY-TEAM> # Replace

>   deploy:
>     name: Deploy
>     needs: build
>     runs-on: ubuntu-latest
>     permissions:
>       contents: read
>       id-token: write
>     steps:
>       - uses: actions/checkout@v6 # Should be pinned
>       - uses: nais/setup@v1 # Should be pinned
>         with:
>           team: <MY-TEAM> # Replace
>       - name: Deploy to Nais
>         run: |
>           # Select the Nais environment. (2)
>           nais apply .nais/app.yaml \
>             --environment <MY-ENV> \
>             --set spec.image="${{ needs.build.outputs.image }}" \
>             --wait
> ```

> 1. GitHub actions should be pinned to a SHA for better security. Read more in GitHub [Secure use reference](https://docs.github.com/en/actions/reference/security/secure-use#using-third-party-actions).
> 2. Environment is the Nais environment to deploy to. You can find the value in [workloads/environments](/workloads/reference/environments.md).

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.

```bash
git add .
git commit -m "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:

**CLI**

```bash
gh run watch
```

**GitHub Web**

- Visit your repository on [GitHub](https://github.com).
- Navigate to `Actions`.
- Select the latest workflow run.

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>.dev-nais.cloud.nais.io`

### Restart your application

Click `+` a few times and note the count. Then restart the application:

```bash
nais app restart <MY-APP> --team <MY-TEAM> --environment <MY-ENV>
```

Wait for the restart to finish, then reload the page. The count is back to 0 because it lives in the application's memory, not in a database.

### Change the greeting

Open `index.html` and change `<h1>Heisann!</h1>` to `<h1>Heisann, Ada!</h1>` (use your own name).

```bash
git add index.html
git commit -m "Personalize the greeting"
git push origin main
```

Watch the new workflow run with `gh run watch`. GitHub Actions builds a new image and deploys it with `nais apply`. When the workflow finishes, reload your application to see the new greeting. You did not need to deploy it manually.

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

- created a github repository
- added the required files for deployment
- deployed our application to Nais

Now it's time to clean up after ourselves.

### Delete your repository

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

**CLI**

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

**GitHub Web**

- Visit your repository on [GitHub](https://github.com).
- Navigate to `Settings`.
- At the bottom of the page, click on `Delete this repository`
- Confirm the deletion

## 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](/workloads/application.md) and [Nais Jobs](/workloads/job.md).

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 deploy manifest changes without building a new image if there are no changes to the application code.
Explore our [complete deploy pipeline](/build/how-to/deploy-pipeline.md) guide for patterns on deploying to multiple environments and splitting workflows.