sushii-image-server <!-- omit in toc -->

Simple local web server made with Express and puppeteer to generate images for sushii-bot. The static directory can be used to serve static files used for HTML screenshots (e.g., JavaScript, css, image files).

⚠ Warning <!-- omit in toc -->

This is intended for requests from trusted services and is not designed for direct public access. Any JavaScript code can be run on the system and local files can be accessed.

Table of Contents <!-- omit in toc -->

• Running
  • With Docker
  • Without Docker
• Configuration
• API Endpoints
• Projects using sushii-image-server

Running

With Docker

docker run \
    -p 3000:3000 \
    --init \
    --rm \
    --cap-add=SYS_ADMIN \
    ghcr.io/sushiibot/sushii-image-server

--cap-add=SYS_ADMIN is needed to run Chromium in a sandbox. If you don't want to provide SYS_ADMIN to the container, you will need to launch Chromium without sandbox by setting SUSHII_IMG_BROWSER_ARGS="--no-sandbox --disable-setuid-sandbox". Keep in mind that running without a sandbox is strongly discouraged and only should be done if you absolutely trust the content you open in Chromium.

--init is used to reap zombie processes.

Example docker-compose.yml configuration:

version: "3.8"
services:
    sushii-image-server:
        image: ghcr.io/sushiibot/sushii-image-server:latest
        container_name: sushii-image-server
        restart: unless-stopped
        init: true
        cap_add:
            - SYS_ADMIN
        expose:
            - "3000"
        volumes:
            # Static files
            - /some/path/static:/app/static:ro
            # Handlebar template files
            - /some/path/templates:/app/templates:ro

Without Docker

1. Install Node.js and npm

2. Clone repository and enter the directory.

   git clone https://github.com/sushiibot/sushii-image-server.git
   cd sushii-image-server
   

3. Install sushii-image-server dependencies.

   yarn
   

4. Install chromium dependencies. You can check if you are missing dependencies with ldd chrome | grep not.

   Example command to install common dependencies for Debian based systems:

   sudo apt-get install -y gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget
   

5. Build TypeScript files and start with yarn start or with a process manager like PM2.

Configuration

Configuration options can be passed via environment variables or an .env file in the base project directory.

Available options with their default values are listed below:

SUSHII_IMG_INTERFACE=0.0.0.0
SUSHII_IMG_PORT=3000
SUSHII_IMG_HEADLESS=true
SUSHII_IMG_BROWSER_ARGS=""
SUSHII_IMG_WIDTH=512
SUSHII_IMG_HEIGHT=512
SUSHII_IMG_IMAGE_FORMAT=png
SUSHII_IMG_QUALITY=70

API Endpoints

• POST /url

  Generate a screenshot of given url

  | Parameter | Description | Default Value | | :---------- | :----------------------------------------- | ------------- | | url | URL to generate a screenshot of (required) | | | width | Screenshot width | 512 | | height | Screenshot height | 512 | | imageFormat | Image format (png or jpeg) | png | | quality | Jpeg image quality (0-100) | 70 |

  curl localhost:3000/url \
      -d url=https://google.com \
      -d width=1280 \
      -d height=720 \
      -d imageFormat=jpeg \
      -d quality=90 > image.jpg
  

• POST /html

  Generate a screenshot of given HTML

  | key | Description | Default Value | | :---------- | :------------------------------------------ | ------------- | | html | HTML to generate a screenshot of (required) | | | width | Screenshot width | 512 | | height | Screenshot height | 512 | | imageFormat | Image format (png or jpeg) | png | | quality | Jpeg image quality (0-100) | 70 |

  curl localhost:3000/html \
      -d html=hi \
      -d width=1280 \
      -d height=720 \
      -d imageFormat=png > image.png
  

• POST /template

  Generate a screenshot of Handlebars template. One of templateHtml or templateName is required. Template data should be passed as JSON in the request body.

  | Key | Description | Default Value | | :----------- | :------------------------------------------- | ------------- | | templateHtml | Handlebars template HTML | | | templateName | Name of Handlebars template in ./templates | | | width | Screenshot width | 512 | | height | Screenshot height | 512 | | imageFormat | Image format (png or jpeg) | png | | quality | Jpeg image quality (0-100) | 70 | | context | JSON context for Handlebars replacement | |

  curl localhost:3000/template \
      -d templateName=test \
      -d context='{"name": "Bob" }' \
      -d width=1280 \
      -d height=720 \
      -d imageFormat=png > image.png
  
  curl localhost:3000/template \
      -d templateHtml="<p>Hello, {{name}}</p>" \
      -d context='{"name": "Bob" }' \
      -d width=1280 \
      -d height=720 \
      -d imageFormat=png > image.png
  

• GET /metrics

  Get image server prometheus metrics. Uses prom-client which includes process metrics in addition to sushii image metrics. API request metrics are under sushii_image_server_http_requests_total with the labels endpoint, method, status.

Projects using sushii-image-server

• sushii bot
• haseul bot
• hyejoo bot
• miso bot
• bento bot
• Use sushii-image-server? Feel free to open a PR to add to the list!