docs: improve documentation, add nodejs serve guide, add encryption docs

.github/actions/setup/action.yml

@@ -0,0 +1,16 @@
+name: "Setup"
+description: "Setup node/pnpm version and install dependencies"
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 20
+        cache: pnpm
+        cache-dependency-path: pnpm-lock.yaml
+    - uses: pnpm/action-setup@v2
+      with:
+        version: 8
+    - run: pnpm install --frozen-lockfile
+      shell: bash

.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - next
+    tags:
+      - "*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup.yml
+      - run: pnpm test
+
+  publish-docs:
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup.yml
+      - run: pnpm docs:build
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/.vitepress/dist
+
+  publish-docker:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v1
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/login-action@v1
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USER }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Get tag version
+        id: prep
+        run: |
+          if [[ $GITHUB_REF == refs/heads/main ]]; then
+            echo "version=latest" >> $GITHUB_OUTPUT
+          elif [[ $GITHUB_REF == refs/heads/next ]]; then
+            echo "version=nightly" >> $GITHUB_OUTPUT
+          else
+            echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          fi
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository_owner }}/url-to-png:${{ steps.prep.outputs.version }}
+            ${{ secrets.DOCKERHUB_USER }}/url-to-png:${{ steps.prep.outputs.version }}

.prettierignore

@@ -0,0 +1,3 @@
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+node_modules/

README.md

@@ -1,15 +1,13 @@
 <h1 align="center">
-  	<img style="height:200px;padding:0;" height="100" src="https://res.cloudinary.com/jmondi/image/upload/v1536798191/jasonraimondi.com/url-to-img/url-to-png-logo.png" alt="URL-to-PNG logo" />
-  	URL-to-PNG
+  	<img height="100" src="https://res.cloudinary.com/jmondi/image/upload/v1536798191/jasonraimondi.com/url-to-img/url-to-png-logo.png" alt="URL to PNG logo" />
+  	<br /> URL to PNG
 </h1>
 
-![GitHub License](https://img.shields.io/github/license/jasonraimondi/url-to-png)
-[![GitHub Workflow Status]( https://img.shields.io/github/actions/workflow/status/jasonraimondi/url-to-png/publish.yml?branch=main&style=flat-square)](https://github.com/jasonraimondi/url-to-png)
-![Docker Pulls](https://img.shields.io/docker/pulls/jasonraimondi/url-to-png)
+[![GitHub License](https://img.shields.io/github/license/jasonraimondi/url-to-png)](https://github.com/jasonraimondi/url-to-png/blob/main/LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/jasonraimondi/url-to-png/ci.yml?branch=main&style=flat-square)](https://github.com/jasonraimondi/url-to-png)
+[![Docker Pulls](https://img.shields.io/docker/pulls/jasonraimondi/url-to-png)](https://hub.docker.com/r/jasonraimondi/url-to-png/tags)
 
-URL-to-PNG is a server that generates PNG images from URLs over HTTP. It provides a simple API that can be accessed via query parameters passed to the server's single endpoint.
-
-### Features
+A URL to PNG generator over HTTP with a fairly simple API accessed via query params passed to the server.
 
 - Generate PNG images from URLs
 - Customizable image dimensions and viewport size
@@ -19,3 +17,41 @@ URL-to-PNG is a server that generates PNG images from URLs over HTTP. It provide
 - Configurable Playwright options
 - Integration with various storage providers (AWS S3, CouchDB, Filesystem)
 - Prometheus metrics endpoint
+
+## Getting Started
+
+Checkout [the docs to getting_started](https://jasonraimondi.github.io/url-to-png/getting_started/)
+
+### Docker
+
+Run the following command:
+
+```
+docker run --rm -p 3089:3089 ghcr.io/jasonraimondi/url-to-png
+```
+
+On the hub: [Link to DockerHub](https://hub.docker.com/r/jasonraimondi/url-to-png/)
+
+### Local Serve
+
+Serve the project
+
+```
+git clone https://github.com/jasonraimondi/url-to-png
+cd url-to-png
+pnpm install
+pnpm exec playwright install chromium
+pnpm dev
+```
+
+## Configuration
+
+Read the [full config options](https://jasonraimondi.github.io/url-to-png/config/)
+
+## Encryption
+
+Learn about [encryption](https://jasonraimondi.github.io/url-to-png/encryption/)
+
+## Metrics
+
+Learn about [metrics](https://jasonraimondi.github.io/url-to-png/metrics/)

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '3.7'
+version: "3.7"
 services:
   urltopng:
     image: jasonraimondi/url-to-png
@@ -10,13 +10,13 @@ services:
       LOG_LEVEL: debug
       NODE_ENV: debug
       BROWSER_WAIT_UNTIL: networkidle
-#      STORAGE_PROVIDER: s3
-#      AWS_ACCESS_KEY_ID: miniominiominio
-#      AWS_SECRET_ACCESS_KEY: miniominiominio
-#      AWS_DEFAULT_REGION: us-east-1
-#      AWS_ENDPOINT_URL_S3: http://minio:9000
-#      AWS_FORCE_PATH_STYLE: true
-#      AWS_BUCKET: url-to-png-uploads
+      #      STORAGE_PROVIDER: s3
+      #      AWS_ACCESS_KEY_ID: miniominiominio
+      #      AWS_SECRET_ACCESS_KEY: miniominiominio
+      #      AWS_DEFAULT_REGION: us-east-1
+      #      AWS_ENDPOINT_URL_S3: http://minio:9000
+      #      AWS_FORCE_PATH_STYLE: true
+      #      AWS_BUCKET: url-to-png-uploads
       STORAGE_PROVIDER: couchdb
       COUCH_DB_PROTOCOL: http
       COUCH_DB_HOST: couchdb

docs/.vitepress/config.ts

@@ -7,12 +7,22 @@ export default defineConfig({
   base: "/url-to-png/",
   description:
     "Selfhosted. URL-to-PNG utility featuring parallel rendering using Playwright for screenshots and with storage caching via Local, S3, or CouchDB.",
+  head: [
+    [
+      "script",
+      {
+        "data-domain": "jasonraimondi.github.io/url-to-png",
+        src: "https://plausible.io/js/script.js",
+        defer: "true",
+      },
+    ],
+  ],
   themeConfig: {
     repo: "jasonraimondi/url-to-png",
     docsDir: "docs",
     editLink: {
-      pattern: 'https://github.com/jasonraimondi/url-to-png/edit/main/docs/:path',
-      text: 'Edit this page on GitHub'
+      pattern: "https://github.com/jasonraimondi/url-to-png/edit/main/docs/:path",
+      text: "Edit this page on GitHub",
     },
     nav: [
       { text: "Github", link: "https://github.com/jasonraimondi/url-to-png" },
@@ -21,13 +31,18 @@ export default defineConfig({
     sidebar: [
       {
         items: [
+          { text: "/", link: "/" },
           { text: "Getting Started", link: "/getting_started/" },
+          { text: "Usage", link: "/usage/" },
           { text: "Configuration", link: "/config/" },
-          { text: "Storage Providers", link: "/storage_providers/" },
+          { text: "Encryption", link: "/encryption/" },
           { text: "Metrics", link: "/metrics/" },
-          { text: "Contributing", link: "/contributing/" },
         ],
       },
     ],
+    footer: {
+      message: "Released under the MIT License.",
+      copyright: "Copyright © 2024 Jason Raimondi",
+    },
   },
 });

docs/.vitepress/theme/custom.css

@@ -0,0 +1,18 @@
+ul.table-of-contents {
+  list-style-type: none;
+  margin: 1rem 0 0 0.5rem;
+  padding: 0;
+  line-height: 1;
+}
+
+ul.table-of-contents ul {
+  margin-left: 1rem;
+}
+
+.table-of-contents li {
+  text-indent: -5px;
+}
+.table-of-contents li:before {
+  content: "- ";
+  text-indent: -5px;
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,5 @@
+// .vitepress/theme/index.js
+import DefaultTheme from "vitepress/theme";
+import "./custom.css";
+
+export default DefaultTheme;

docs/config/index.md

@@ -1,6 +1,6 @@
 # Configuration
 
-URL-to-PNG allows you to configure various settings through environment variables. Here are the available configuration options:
+Configure various settings through environment variables.
 
 ## General Settings
 
@@ -32,28 +32,39 @@ URL-to-PNG allows you to configure various settings through environment variable
 
 ## Storage Providers
 
-- `STORAGE_PROVIDER`: Storage provider to use. Valid options: `stub`, `s3`, `couchdb`, `filesystem`. Default: `stub`.
+The project supports multiple storage providers for caching rendered images. The storage provider can be configured using the `STORAGE_PROVIDER` environment variable. The available storage providers are:
 
-### Filesystem Storage Provider
+### Stub Storage Provider (default)
 
-- `IMAGE_STORAGE_PATH`: Path to store images when using the filesystem storage provider.
+The stub storage provider is a placeholder storage provider that doesn't actually store or retrieve images, it simply logs debug messages. It can be used for testing or when storage functionality is not required.
 
-### S3 Storage Provider
+### Filesystem
 
-- `AWS_BUCKET`: AWS S3 bucket name.
-- `AWS_ACCESS_KEY_ID`: AWS access key ID.
-- `AWS_SECRET_ACCESS_KEY`: AWS secret access key.
-- `AWS_DEFAULT_REGION`: AWS default region. Default: `us-east-1`.
-- `AWS_ENDPOINT_URL_S3`: AWS S3 endpoint URL.
-- `AWS_FORCE_PATH_STYLE`: Force path-style URLs for S3. Default: `false`.
+The filesystem storage provider allows storing and retrieving rendered images on the local filesystem.
 
-### CouchDB Storage Provider
+- `STORAGE_PROVIDER`: `"filesystem"`
+- `IMAGE_STORAGE_PATH`: The directory path where images will be stored
 
-- `COUCH_DB_HOST`: CouchDB host.
-- `COUCH_DB_PASS`: CouchDB password.
-- `COUCH_DB_PORT`: CouchDB port.
-- `COUCH_DB_PROTOCOL`: CouchDB protocol.
-- `COUCH_DB_USER`: CouchDB username.
-- `COUCHDB_DATABASE`: CouchDB database name. Default: `images`.
+### S3
 
-To configure URL-to-PNG, set the appropriate environment variables either in your `.env` file or pass them as environment variables to your Docker container.
+The S3 compatible storage provider allows storing and retrieving rendered images using Amazon S3.
+
+- `STORAGE_PROVIDER`: `"s3"`
+- `AWS_BUCKET`: The name of the S3 bucket to store images
+- `AWS_ACCESS_KEY_ID`: The AWS access key ID
+- `AWS_SECRET_ACCESS_KEY`: The AWS secret access key
+- `AWS_DEFAULT_REGION`: The AWS region for S3 (default: "us-east-1")
+- `AWS_FORCE_PATH_STYLE`: Set to `true` to use path-style URLs for S3 (default: `false`)
+- `AWS_ENDPOINT_URL_S3`: The endpoint URL for S3 (optional)
+
+### CouchDB
+
+The CouchDB storage provider allows storing and retrieving rendered images using CouchDB.
+
+- `STORAGE_PROVIDER`: `"couchdb"`
+- `COUCH_DB_PROTOCOL`: The protocol for connecting to CouchDB (e.g., "http" or "https")
+- `COUCH_DB_USER`: The CouchDB username
+- `COUCH_DB_PASS`: The CouchDB password
+- `COUCH_DB_HOST`: The CouchDB host
+- `COUCH_DB_PORT`: The CouchDB port
+- `COUCHDB_DATABASE`: The name of the CouchDB database to store images (default: "images")