131 lines
4.3 KiB
Markdown
131 lines
4.3 KiB
Markdown
Composite Gitea/GitHub Actions for building, deploying, and cleaning up Node.js containers behind Pangolin
|
|
|
|
[](https://git.zyrrus.dev/eighty-six/node-deploy-action/releases) [](https://www.docker.com/) [](https://docs.fossorial.io/)
|
|
|
|
Table of Contents
|
|
|
|
- [About the Project](#about-the-project)
|
|
- [Getting Started](#getting-started)
|
|
- [Prerequisites](#prerequisites)
|
|
- [Pangolin API token permissions](#pangolin-api-token-permissions)
|
|
- [Installation](#installation)
|
|
- [Usage](#usage)
|
|
- [Deploy](#deploy)
|
|
- [Cleanup](#cleanup)
|
|
- [Roadmap](#roadmap)
|
|
|
|
## About the Project
|
|
|
|
This repo bundles a small set of composite actions that handle the full lifecycle of a containerized Node.js app: building the Docker image, deploying it to a self-hosted runner, and registering (or tearing down) the corresponding Pangolin resource. The goal is a minimal, opinionated drop-in for production and preview-branch deployments without pulling in a heavy CI platform.
|
|
|
|
## Getting Started
|
|
|
|
Follow these steps to wire the actions into a repository.
|
|
|
|
### Prerequisites
|
|
|
|
You'll need a self-hosted runner with Docker installed and network access to a Pangolin instance. The following secrets must be available to the workflow.
|
|
|
|
Secret
|
|
|
|
`PANGOLIN_API_URL`
|
|
|
|
`PANGOLIN_API_KEY`
|
|
|
|
`PANGOLIN_ORG_ID`
|
|
|
|
`PANGOLIN_DOMAIN_ID`
|
|
|
|
`PANGOLIN_SITE_ID`
|
|
|
|
`PANGOLIN_TARGET_IP`
|
|
|
|
A `dockerfile` at the repo root is expected by the `deploy` action. See `examples/docker/` for Next.js and Astro templates.
|
|
|
|
#### Pangolin API token permissions
|
|
|
|
The `PANGOLIN_API_KEY` must be scoped to the following actions (API v1):
|
|
|
|
- `GET /org/{id}/resources`
|
|
- `PUT /org/{id}/resource`
|
|
- `POST /resource/{id}`
|
|
- `DELETE /resource/{id}`
|
|
- `GET /resource/{id}/targets`
|
|
- `PUT /resource/{id}/target`
|
|
- `DELETE /target/{id}`
|
|
|
|
### Installation
|
|
|
|
No installation is needed — reference the actions directly from a workflow.
|
|
|
|
- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/deploy@v1
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
> **⚠️ Warning:**
|
|
> This action is tailored to a specific self-hosted runner + Pangolin setup. Adapt the scripts before reusing elsewhere.
|
|
|
|
See `examples/deploy.yml` for a complete workflow covering production, preview, and cleanup.
|
|
|
|
### Deploy
|
|
|
|
Builds the Docker image, starts the container, and registers a Pangolin resource. The branch name drives everything else: pushes to the repo's default branch deploy as `production`, all other branches deploy as previews with a slugified tag, a deterministic host port, and a `${slug}.${app-name}` subdomain.
|
|
|
|
- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/deploy@v1
|
|
with:
|
|
app-name: my-app
|
|
branch: ${{ github.ref_name }}
|
|
|
|
Inputs
|
|
|
|
`app-name`
|
|
|
|
Application name (used for image/container naming, and as the production subdomain)
|
|
|
|
`branch`
|
|
|
|
Branch name. Matches against `github.event.repository.default_branch` to decide production vs. preview. `refs/heads/` prefix is stripped.
|
|
|
|
`internal-port`
|
|
|
|
Port the app listens on inside the container (default `3000`)
|
|
|
|
`build-args`
|
|
|
|
Extra `KEY=VALUE` docker build args (space-separated)
|
|
|
|
`env-vars`
|
|
|
|
Runtime env vars for the container, one `KEY=VALUE` per line. Merged on top of `/opt/apps/${app-name}/.env.${environment}` on the runner — keys defined here win. Reference secrets here so values stay masked in logs.
|
|
|
|
env-vars: |
|
|
DATABASE_URL=${{ secrets.DATABASE_URL }}
|
|
API_KEY=${{ secrets.API_KEY }}
|
|
|
|
### Cleanup
|
|
|
|
Stops the preview container and removes its Pangolin resource. Intended for `delete` branch events — the slug is derived from the branch name internally.
|
|
|
|
- uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/cleanup@v1
|
|
with:
|
|
app-name: my-app
|
|
branch: ${{ github.event.ref }}
|
|
|
|
## Roadmap
|
|
|
|
- Core actions
|
|
- Build + deploy container
|
|
- Register Pangolin resource
|
|
- Preview slug + deterministic port
|
|
- Cleanup on branch delete
|
|
- Dockerfile templates
|
|
- Next.js
|
|
- Astro
|
|
- Remix / SvelteKit
|
|
- Quality of life
|
|
- Configurable Docker build context
|
|
- Health-check gating before Pangolin registration
|
|
- Multi-arch image builds
|