Added Astro.js guide

2026-04-30 21:16:43 -05:00
parent f4653456f3
commit 17c79eb6bd
4 changed files with 163 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,149 @@
+Composite Gitea/GitHub Actions for building, deploying, and cleaning up Node.js containers behind Pangolin
+
+[![Release v1](https://img.shields.io/badge/v1-996677?colorA=151515&style=for-the-badge)](https://git.zyrrus.dev/eighty-six/node-deploy-action/releases) [![Docker](https://img.shields.io/badge/Docker-2496ed?logo=docker&logoColor=white&style=for-the-badge)](https://www.docker.com/) [![Pangolin](https://img.shields.io/badge/Pangolin-151515?style=for-the-badge)](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)
+  - [Slug](#slug)
+  - [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.
+
+    - uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/deploy@v1
+      with:
+        app-name: my-app
+        tag: production
+        port: "3001"
+        environment: production
+        subdomain: my-app
+
+Inputs
+
+`app-name`
+
+Application name (used for image/container naming)
+
+`tag`
+
+Image/container tag (e.g. `production` or a branch slug)
+
+`port`
+
+Host port to expose
+
+`internal-port`
+
+Port the app listens on inside the container (default `3000`)
+
+`environment`
+
+`production` or `preview`
+
+`subdomain`
+
+Subdomain for the Pangolin resource
+
+`build-args`
+
+Extra `KEY=VALUE` docker build args (space-separated)
+
+### Slug
+
+Derives a URL-safe slug and a deterministic port from a branch name. Strips `refs/heads/` so either `github.ref_name` or `github.event.ref` works.
+
+    - id: slug
+      uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/slug@v1
+      with:
+        branch: ${{ github.ref_name }}
+
+Outputs: `slug`, `port`.
+
+### Cleanup
+
+Stops the preview container and removes its Pangolin resource. Intended for `delete` branch events.
+
+    - uses: https://git.zyrrus.dev/eighty-six/node-deploy-action/cleanup@v1
+      with:
+        app-name: my-app
+        slug: ${{ steps.slug.outputs.slug }}
+
+## 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