Minipage

A very simple and basic page deploy tool

Introduction

Forgejo doesn't come with a "Github pages"-tool like to deploy simple pages. And frankly I don't even know how it works and what it does. Codeberg Pages exists but is in maintenance mode. All I need is a tool I can call from a pipeline to deploy files in a folder served by a static server, so I quickly made minipage.

minipage is a server and a client. The server waits for a POST request with the following content:

{
  "name": "pagename",
  "url": "https://www.example.org/example.zip"
}

The name correspond to the name you want your page to be under (so if you serve your pages on https://www.example.org/pages and send a deploy request with name my-repo, it will be served under https://www.example.org/pages/my-repo). The url is the zip archive who's content you want to deploy.

When the server receives the request, it will create a folder with the name you gave it, download the zip archive, and extract it in the previously created folder. If you set up your reverse proxy properly, the page should be deployed. Simple.

Usage

Server

The server has a few arguments, but they all have a default value:

minipage - Simple page deployment tool

Usage:
  minipage [options]

Options:
  -p <port>       Port on which to listen
  -c <config>     Path to the configuration file, relative to the current directory
  -i <interface>  Interface on which to listen
  -l <log_level>  Log level
  -h              Print this help

The configuration file should be a .zon file. Here is an example configuration file:

.{
    .host_url = "example.org",
    .root = "/var/www/html/pages",
}

host_url is used to do some simple filtering. It tells from which host the server is allowed to pull artifacts to deploy. If you send an artifact URL with a different host, the server will refuse to deploy it.

root is the folder on your server where the page will be deployed.

Client

The client takes 3 mandatory arguments:

minipage-client - Client for minipage

Usage:
  minipage-client [options]

Options:
  -u <url>        URL of the minipage server
  -a <artifact>   URL of the artifact to deploy
  -n <name>       Name of the page
  -k              Keep existing files. Returns an error if the page already exists.
  -l <log_level>  Log level
  -h              Print this help

Assuming that the minipage server is started and behind a reverse proxy (at https://www.example.org/minipage), here is an example of a deployment request:

minipage-client -u https://www.example.org/minipage -n my-repo -a https://www.example.org/my-repo/1/artifact.zip

If your server is properly configured, your page should be available on https://www.example.org/minipage/my-repo.