Skip to content

Commit

Permalink
Merge pull request #134 from diogomartino/gh-cicd-improvements
Browse files Browse the repository at this point in the history
docs: github deploy improvements
  • Loading branch information
githubsaturn authored Dec 30, 2023
2 parents 8f0d721 + 27043e7 commit 7f43a99
Showing 1 changed file with 27 additions and 10 deletions.
37 changes: 27 additions & 10 deletions docs/ci-cd-integration/deploy-from-github.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,13 @@ sidebar_label: Deploy from GitHub
This example showcases a Vue 3 app with a PHP backend that can be built, tested and deployed directly from Github to CapRover using the CapRover community-maintained [GitHub Action](https://github.com/caprover/deploy-from-github). Feel free to clone an example project from https://github.com/PremoWeb/SDK-Foundation-Vue to try things out or build your next awesome app.

### Create a new App

The name you choose here will become the APP_NAME secret.

![Create a new app](/img/docs/deploy-from-github/create-a-new-app.png "Create a new app")

### Enable App Token

Find the "Deployment" tab for your new app, click Enable App Token and copy this token. This is your APP_TOKEN secret.

![Create a new app](/img/docs/deploy-from-github/enable-app-token.png "Enable App Token")
Expand Down Expand Up @@ -86,6 +88,7 @@ jobs:
app: '${{ secrets.APP_NAME }}'
token: '${{ secrets.APP_TOKEN }}'
```

A quick breakdown of what you are seeing above:

The first step is to check out and build the Vue 3 frontend part of the app using NPM. The output of the build will be located in frontend/dist/. If present, the app would have also been tested prior to the second step.
Expand All @@ -107,33 +110,47 @@ Alternatively, you can even build the Docker image on Github and just deploy the
In order to achieve this we will need to take the following steps to build the Docker image using GitHub Actions, store it using GitHub Packages, and then deploy it to CapRover.

#### Create a GitHub Personal Access Token

You will need to create a GitHub Personal Access Token with **write permission for packages**.

GitHub has a great guide on creating a personal access token if you have not before. Here is the link: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

#### Create a New App

If you do not have an app already on CapRover, create one using the instructions [here](#create-a-new-app)

If you do already have an app on CapRover you can skip this step.
If you do already have an app on CapRover you can skip this step.

#### Enable App Token

If you do not already have an app token for your app, create one using the instructions [here](#enable-app-token)

If you do have an app token, keep it handy as we will need it in the next step.
If you do have an app token, keep it handy as we will need it in the next step.

#### Add The GitHub Secrets

You will need to add the following information into GitHub Secrets:

- App Name: Name of the app in CapRover
- App Token: App token we got in the previous step
- CapRover Server URL: URL of your CapRover Server
- GitHub Token: GitHub Personal Access Token you created in previous step

You can add GitHub Secrets using the instructions [here](#add-the-github-secrets)

#### Add the Captain Definition File
Add the `captain-definition` file described [here](#add-files-to-project)
#### Add a private Docker Registry to CapRover

In order to pull the image from GitHub Packages, you will need to add a private Docker registry to CapRover. If you haven't done this before, you can do this by following the instructions [here](https://caprover.com/docs/app-scaling-and-cluster.html#add-a-private-docker-registry)

Use these values:

- Username: `<your github username>`
- Password: `<your github personal access token>`
- Domain: `ghcr.io` (no www, no http)
- Image Prefix: `<your github username or your org username>` (if you're pulling images from an org different than your username)

#### Create the GitHub Action

GitHub Actions is the CI/CD pipeline built into GitHub. If you are unfamiliar with it, it would be beneficial to learn the basics by reviewing GitHub's Understanding GitHub Actions Docs: https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions

Here is an example GitHub Action that builds a docker container on each push to a pull request and deploys it to the CapRover server (good example for a development environment set up)
Expand All @@ -153,13 +170,13 @@ jobs:
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v1
- name: Login to Container Registry
uses: docker/login-action@v2
with:
registry: ghcr.io
username: ${{ github.repository_owner }}
password: ${{ secrets.GH_TOKEN }}
password: ${{ secrets.GITHUB_TOKEN }}
- name: Preset Image Name
run: echo "IMAGE_URL=$(echo ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}:$(echo ${{ github.sha }} | cut -c1-7) | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
Expand All @@ -179,21 +196,21 @@ jobs:
app: "${{ secrets.APP_NAME }}"
token: "${{ secrets.APP_TOKEN }}"
image: ${{ env.IMAGE_URL }}
```
```

Here is a quick explanation of what each step in the action does:

1. **Check out repository**: This step uses the action `actions/checkout@v2`, which is a predefined GitHub Action that allows the workflow to access the contents of the repository. The checkout action will clone the repository onto the runner (the virtual environment that GitHub Actions uses to execute workflows), so all the subsequent steps in the workflow can operate on it.
2. **Set up Docker Buildx**: This step uses the action `docker/setup-buildx-action@v1`, which is a Docker action to set up Docker Buildx. This allows for more advanced container building capabilities.
3. **Login to Container Registry**: This step uses `docker/login-action@v2` to log into the GitHub Container Registry (ghcr.io) using the repository owner's username and a GitHub Token (GH_TOKEN). This token must have been previously stored in the repository's secrets.
3. **Login to Container Registry**: This step uses `docker/login-action@v2` to log into the GitHub Container Registry (ghcr.io) using the repository owner's username and a GitHub Token (GITHUB_TOKEN). This token must have been previously stored in the repository's secrets.
4. **Preset Image Name**: This is a shell command that constructs the URL for the Docker image. It uses the GitHub repository owner, the repository name, and the SHA of the current commit (truncated to the first 7 characters) to construct a URL, converting all upper-case characters to lower-case, and then writes this URL into the `GITHUB_ENV` so it can be used by subsequent steps as an environment variable.
5. **Build and push Docker Image**: This step uses `docker/build-push-action@v4` to build the Docker image using the Dockerfile in the repository and pushes it to the GitHub Container Registry at the URL that was set in the previous step. The `context: .` setting indicates that the build context is the current directory (i.e., the root of the repository).
6. **Deploy Image to CapRover**: This step uses `caprover/deploy-from-github@v1.1.2` action to deploy the Docker image that was just built and pushed to CapRover. The details of the CapRover server, the application name, and an access token are provided from the repository's secrets. The Docker image URL is taken from the environment variable set earlier.

#### Deploy!
After these changes are implemented commit + push them to your repo and watch the magic happen 🪄


After these changes are implemented commit + push them to your repo and watch the magic happen 🪄

### Need help?

Commercial and community support is available. Please visit the [Help and Support](/docs/support.html "Help and Support") page for details.

0 comments on commit 7f43a99

Please sign in to comment.