# How To Deploy a Static Website from Gitea Using Git Hooks

### Introduction

The popular source code management system [Git](https://git-scm.com) is quite flexible when it comes to allowing you to perform various tasks when actions are taken on a repository. For example, you might want to send an email when a feature branch is merged into your main branch, or log various Git actions to a file for tracking.

These actions are called **hooks**, and there are several that you can use for various steps along the way to perform additional work within your Git workflow. For example:

* `post-receive` hooks can be used to perform actions when a commit is pushed to the repository and are useful for CI/CD.
* `post-merge` hooks can be used to perform actions after a merge has been completed and are useful for logging and notifications.
* `post-checkout` hooks can be used to perform actions after you run `git checkout` and are useful for setting up project environments.

For this tutorial, we will be looking at using the `post-receive` hook. A common usage for the hook is running some form of continuous integration or deployment. This might mean running tests or deploying a project. For this example, we will be automatically deploying changes to a static HTML site served by Nginx.

## Prerequisites

Gitea is a lightweight and flexible source code management system that will be used for the examples here, so before beginning this tutorial, you should have the following:

* An Ubuntu 20.04 server with a non-root user configured with `sudo` privileges as described in the [Initial server setup for Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-ubuntu-20-04) tutorial.
* Docker installed on your server as described by **Steps 1 and 2** of our guide on [How to Install Docker on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-20-04).
* Docker Compose installed on your server. Follow **Step 1** of our guide on [How to Install and Use Docker Compose on Ubuntu 20.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-20-04#step-1-installing-docker-compose).
* A domain name pointed at your server. If you are using a DigitalOcean Droplet, you can accomplish this by following our [Domains and DNS](https://docs.digitalocean.com/products/networking/dns/) documentation. This tutorial will use <^>your_domain<^> in examples throughout.
* Gitea installed on the server behind Nginx, ready to interact with using Git over SSH as described in [How To Install Gitea on Ubuntu Using Docker](https://www.digitalocean.com/community/tutorials/how-to-install-gitea-on-ubuntu-using-docker).


## Step 1 — Creating a Static HTML Project in Gitea

To begin with, you will need a repository set up in Gitea. Create a new repository using the **+** button in the upper right corner of the Gitea page. Name it something memorable such as the domain name that it will be deployed to. Fill out the rest of the new repository information and click **Create Repository**.

[![Creating a new repository](TODO)](TODO)

For this tutorial, you'll be setting up a static site at `static.<^>your_domain<^>`, but be sure to replace this with your final site's domain. Now, wherever you plan on developing, check out that repository using `git clone`:

```command
git clone git@<^>your_domain<^>:<^>username<^>/static.<^>your_domain<^>
```

Move into that directory using `cd`:

```command
cd static.<^>your_domain<^>
```

Now, create a file named `index.html` which will be served by Nginx. The following example uses `nano`. This file will contain a little bit of text that we can view in the browser.

```command
nano index.html
```

Within that file, add a snippet of HTML that you will recognize:

```html
[label index.html]
<html>
    <head>
        <title>Testing Gitea</title>
    </head>
    <body>
        <h1>It works!</h1>
    </body>
</html>
```

Save and close the file. If you used `nano` to edit the file, you can do so by pressing `Ctrl + X`,  `Y`, and then `Enter`.

Now, add the file to the git working tree:

```command
git add index.html
```

Now that the file is added, commit your changes:

```command
git commit -m "Added index.html"
```

Push your changes up to your Gitea repository:

```command
git push origin main
```

<$>[note]
**Note:** In this example, we are working on the branch named **main**. Your default branch may be named something else such as **master**. In order to find out the name of your current branch, you can run `git branch`.
<$>

## Step 2 — Creating a Static HTML Site in Nginx

Now, let's set up Nginx to serve our static site. Create a new file in `/etc/nginx/sites-available` using your text editor:

```command
sudo nano /etc/nginx/sites-available/static.<^>your_domain<^>
```

In this file, enter the following:

```nginx
[label /etc/nginx/sites-available/static.<^>your_domain<^>]
server {
	server_name static.<^>your_domain<^>;
	listen 80;

	root /var/www/static.<^>your_domain<^>;

    index index.html;
    
	location / {
		try_files $uri $uri/ =404;
	}
    
    location /.git {
        return 404;
    }
}
```

This `server` block instructs Nginx to listen on the standard HTTP port 80 for requests to `static.<^>your_domain<^>`. When it receives a request, it tries to find a file matching that request in `/var/www/static.<^>your_domain<^>`. It will first try looking for the file named (for instance, if you visit `static.<^>your_domain<^>/shark.jpg`, it will try to find `/var/www/static.<^>your_domain<^>/shark.jpg`). If that does not exist, it will append a `/` to the end of the file name to serve a directory or the file named `index.html`. Finally, if none of those work, it will serve a 404 Not Found error.

We also don't want anyone accessing our `.git` directory, so the next `location` block instructs Nginx to return a 404 should someone try.

Now, link this file from `sites-available` to `sites-enabled`:

```command
sudo ln -s /etc/nginx/sites-available/static.<^>your_domain<^> /etc/nginx/sites-enabled/static.<^>your_domain<^>
```

In order to make sure everything looks good, you can test the new configuration:

```command
sudo nginx -t
```

If all has gone well, you should see something like the following:

```
[secondary_label Output]
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
```

Restarting the server will make these changes live.

```command
sudo systemctl restart nginx
```

We need to create the repository for there to be anything to serve, however. Move to `/var/www` where you can create the directory for hosting the site:

```command
cd /var/www
```

Make the directory you specified in your server block above:

```command
sudo mkdir static.<^>your_domain<^>
```

You will need to change the permissions on this directory so that both you and the `git` user have write access.

```command
sudo chown <^>username<^>:git static.<^>your_domain<^>
sudo chmod g+x static.<^>your_domain<^>
```

Move to that directory:

```command
cd static.<^>your_domain<^>
```

Now that you have the directory set up, you can clone the repository into it. Rather than using SSH, which would require a key, you can use the `file://` protocol for Git. This works because Nginx is running on the same server that the repository lives on. If the repository is public, you can also use the `https://` protocol.

```command
git clone file:///<^>path_to_gitea_installation<^>/repositories/sammy/static.<^>your_domain<^>.git .
```

It's important to remember to add that `.` at the end of the `git clone` command, as this tells Git to check out the repository into the current directory rather than making a new one. Now, if you type `ls`, you should see the file `index.html` from  your repository, and if you visit the domain you set up, you should see your page rendered.

[![The static webpage](TODO)](TODO)

## Step 3 — Using Git Hooks to Publish Changes

Now that Nginx is serving the site from our checked out repository, we can set up the `post-receive` hook to update the site.

### Creating the Hook Script

Git hooks for Gitea live in the repository that Gitea serves from. These are located in the data directory, predictably within the `repositories` subdirectory. Move to your data directory using `cd`, then move to your repository's `hooks` directory:

```command
cd git/repositories/<^>username<^>/static.<^>your_domain<^>.git/hooks
```

If you list the files in this directory, you will see a whole host of sample scripts, plus a few directories:

```
[secondary_label Output]
total 92
drwxr-xr-x 6 git git 4096 Jun 27 17:29 ./
drwxr-xr-x 7 git git 4096 Jun 27 17:43 ../
-rwxr-xr-x 1 git git  478 Jun 27 17:29 applypatch-msg.sample*
-rwxr-xr-x 1 git git  896 Jun 27 17:29 commit-msg.sample*
-rwxr-xr-x 1 git git  376 Jun 27 17:29 post-receive*
drwxr-xr-x 2 git git 4096 Jun 27 17:29 post-receive.d/
-rwxr-xr-x 1 git git  189 Jun 27 17:29 post-update.sample*
-rwxr-xr-x 1 git git  424 Jun 27 17:29 pre-applypatch.sample*
-rwxr-xr-x 1 git git 1643 Jun 27 17:29 pre-commit.sample*
-rwxr-xr-x 1 git git  416 Jun 27 17:29 pre-merge-commit.sample*
-rwxr-xr-x 1 git git 1374 Jun 27 17:29 pre-push.sample*
-rwxr-xr-x 1 git git 4898 Jun 27 17:29 pre-rebase.sample*
-rwxr-xr-x 1 git git  376 Jun 27 17:29 pre-receive*
drwxr-xr-x 2 git git 4096 Jun 27 17:29 pre-receive.d/
-rwxr-xr-x 1 git git  544 Jun 27 17:29 pre-receive.sample*
-rwxr-xr-x 1 git git 1492 Jun 27 17:29 prepare-commit-msg.sample*
-rwxr-xr-x 1 git git  134 Jun 27 17:29 proc-receive*
drwxr-xr-x 2 git git 4096 Jun 27 17:29 proc-receive.d/
-rwxr-xr-x 1 git git 2783 Jun 27 17:29 push-to-checkout.sample*
-rwxr-xr-x 1 git git  356 Jun 27 17:29 update*
drwxr-xr-x 2 git git 4096 Jun 27 17:29 update.d/
-rwxr-xr-x 1 git git 3650 Jun 27 17:29 update.sample*
```

For our purposes, we will be creating a new script within the `post-receive.d` directory. On Linux, configuration and scripts are usually stored in a directory such as `/etc/apt` or our `hooks` directory. However, if there are multiple configuration files or scripts, they may be divided up and placed in a `*.d` directory, and the service which uses them will read all of those files in list order.

Open a new file in `post-receive.d` for editing named `deploy`:

```command
nano post-receive.d/deploy
```

This file can be any executable script. In our case, since we'll just be running a simple `git` command, we'll use a Bash script. Enter the following into that file:

```bash
[label post-receive.d/deploy]
#!/bin/bash

set -eux

git --git-dir=/var/www/static.<^>your_domain<^>/.git --work-tree=/var/www/static.<^>your_domain<^>/ pull --ff-only
```

Let's break this script down into its parts to understand what's happening:

* `#!/bin/bash` tells the shell to use the bash command to run the script.
* `set -eux` specifies three options: `e` means that the script will exit on a failure, `u` means that unset variables will be an error, and `x` means that it will print the commands as it executes them. These options are good practice for preventing scripts from continuing to execute when there are errors.
* The `git` command breaks down into `git pull` which pulls new changes from the repository, while the `--work-tree` and `--git-dir` options tell Git to use the `.git` directory within the checked out branch for all of its configuration. `--ff-only` instructs `git pull` to use fast-forward reconciliation when pulling new commits.

Once you're done editing the script and have saved and closed it, use `chmod` to make the script executable:

```command
chmod a+x post-receive.d/deploy
```

### For Gitea Running in Docker

If Gitea is running in a Docker container --- if, for instance, you deployed it using the Docker Compose method in the tutorial linked above --- you will need to make a few changes to make the repository accessible from within the container. First, edit the `docker-compose.yml` file and move to the `volumes:` entry. Add a new line to that list:

```yaml
[label docker-compose.yml]
    volumes:
      ...
      <^>- /var/www/static.<^>your_domain<^>:/var/www/static.<^>your_domain<^><^>
```

This will mount that directory as a volume that the container can access. You will need to restart your Gitea containers:

```command
docker-compose down
docker-compose up
```

Next, you will need to change the remote URL for the repository to the proper location for within the Docker container.

```command
git remote set-url origin file:///data/git/repositories/sammy/static.<^>your_domain<^>.git
```

Here, we've changed the original URL we used to check out the branch from `/<^>path_to_gitea_installation<^>/repositories/sammy/static.<^>your_domain<^>.git` to use `/data/git/` as the path to the installation, as that is how the volume is mapped in `docker-compose.yml`. As always, be sure to use the username and repository name appropriate to your project.

### Testing the `post-receive` Hook

Now, after Gitea receives a new commit and it's written to disk, it will run this script to update the branch checked out in `/var/www/static.<^>your_domain<^>`. To test this out, change the `index.html` file on your local working directory to include a congratulations message. For example, change the file so that it resembles this:

```html
[label index.html]
<html>
    <head>
        <title>Testing Gitea</title>
    </head>
    <body>
        <h1>It works!</h1>
        <p>Congratulations on setting up a <code>post-receive</code> hook!
    </body>
</html>
```

After saving and exiting the file, commit your changes:

```command
git commit -am "Added congratulations message"
```

And push your changes:

```command
git push origin main
```

This time, you should see some additional output from Git. Because you set the `-x` option in our deploy script, you'll see the output of that script during the process, prefixed with `remote:`.

```
[secondary_label Output]
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 312 bytes | 312.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
remote: + cd /var/www/static.<^>your_domain<^>
remote: + git --git-dir=/var/www/static.<^>your_domain<^>/.git pull --ff-only
remote: From file:///data/git/repositories/<^>username<^>/static.<^>your_domain<^>
remote:    28c52bf..95cde6f  main       -> origin/main
remote: Updating 28c52bf..95cde6f
remote: Fast-forward
remote: . Processing 1 references
remote: Processed 1 references in total
To <^>your_domain<^>:<^>username<^>/static.<^>your_domain<^>.git
   8eed10f..95cde6f  main -> main
```

When you visit your page in the browser, you should see your now congratulations message displayed.

## Conclusion

In this tutorial, you learned how to use Git hooks in Gitea. While you used the `post-receive` hook to deploy a static website, there are many available hooks that can help you accomplish a wide variety of tasks during your Git workflow. For more information on these hooks, the Git manual has [an in-depth chapter](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) on using them.
