needforheatmanualserver

README

NeedForHeat manual server

Server that server NeedForHeat manuals written in Markdown.

Table of contents

• Deploying
• Developing
• Usage
• Features
• Status
• License
• Credits

Deploying

For our process to deploy the API to our public server, or update it, see these links:

• Deploy: https://github.com/energietransitie/twomes-backoffice-configuration#manuals
• Update: https://github.com/energietransitie/twomes-backoffice-configuration#updating

Prerequisites

The NeedForHeat manual server is available as a Docker image. You will need to install Docker to run it.

Images

See all available images:

• Use the latest tag to get the latest stable release built from a tagged GitHub release.
• Use the main tag to get the latest development release, built directly from the main branch.

Docker Compose (more information)

version: "3.8"
services:
  web:
    container_name: needforheat-manual-server
    image: ghcr.io/energietransitie/needforheat-manual-server:latest
    ports:
      - 8080:8080
    volumes:
      - ./source:/source
    environment:
      - NFH_MANUAL_SOURCE=./source
      - NFH_FALLBACK_LANG=en-US

Developing

This section describes how you can change the source code using a development environment and compile the source code into a binary release of the firmware that can be deployed, either via the development environment, or via the method described in the section Deploying.

Prerequisites

• Go (minimum 1.20)
• Docker

Running

Make sure Docker is running on your local machine, then start the service from a command line terminal from the root of this repository:

docker compose up --build

This generates log messages. Just keep this running in your terminal.

The manuals are now available on http://localhost:8080/.

Usage

Writing manuals

Manuals are written in Markdown. The Markdown files should be placed in a folder structure following some rules. Read this document to see what the folder structure has to be, which files to place in it and what names to give them.

Manuals can be written by device firmware makers. Read this document to see how you can write manuals for a specific device when making firmware for it.

Device display names

Device display names can be retrieved from /devices/<device-name>.

This will return a json object with display names in different languages.

Device manuals

Device manuals can be retrieved from /devices/<device-name>/<manual-type>.

A generic manual (not specific to a campaign) can be retrieved from /devices/<device-name>/. This will auto redirect to /devices/<device-name>/generic.

If you try to retrieve a manual of a specific type that does not exist, you will be redirected to the 'manufacturer' version if it exists.

Manuals from /devices/<device-name>/<manual-type> will automatically redirect to the language that your browser requests using the Accept-Language header. e.g. /devices/<device-name>/<manual-type>/en-US/ for a British English version.

Campaign manuals

Campaign manuals can be retrieved from /campaigns/<campaign-name>/<manual-type>.

A generic manual (not specific to a campaign, but more generic to the lab e.g. privacy policy) can be retrieved from /campaigns/<manual-type>/. This will auto redirect to /campaigns/generic/<manual-type>.

Manuals from /campaigns/<campaign-name>/<manual-type> will automatically redirect to the language that your browser requests using the Accept-Language header. e.g. /campaigns/<campaign-name>/<manual-type>/en-US/ for a British English version.

Features

Ready:

• Parse markdown files to HTML manuals.
• Serve HTML files.
• Redirect to correct language based on Accept-Language header.
• Redirect to generic campaign if none is specified.
• Redirect to device firmware repository for missing manuals.
• Manual source can be set to local directory or git repository.

To-do:

• Watching for file changes and update without restarting the server.
• Get page titles from display_names.json for language automatically when generating HTML.
• A friendly "manual not found" (404) page that can contain contact information if desired.
• Support authentication for private git repositories.

Status

Project is: in progress

License

This software is available under the Apache 2.0 license, Copyright 2023 Research group Energy Transition, Windesheim University of Applied Sciences

Credits

This software is created by:

• Nick van Ravenzwaaij · @n-vr

Product owner:

• Henri ter Hofte · @henriterhofte · Twitter @HeNRGi

We use and gratefully acknowlegde the efforts of the makers of the following source code and libraries:

• chi, by Peter Kieltyka, Google Inc, licensed under MIT license
• markdown, by Russ Ross, Krzysztof Kowalczyk, licensed under BSD 2-clause license
• go-git, by Sourced Technologies, S.L., lincensed under Apache 2.0 license

Documentation

Index

• Variables
• func ChooseFile(options []language.Tag, fallback language.Tag, acceptLangHeader string) (string, error)
• func HTTPError(w http.ResponseWriter, code int)
• func ParseLanguageFiles(fsys fs.FS, folder string) ([]language.Tag, error)
• type Handler
  • func (fn Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerError
  • func NewHandlerError(err error, code int) *HandlerError
  • func (e HandlerError) Error() string
• type Server
  • func NewServer(fsys fs.FS, options ServerOptions) *Server
• type ServerOptions

Variables

var (
	ErrFallbackInvalid = errors.New("fallback is invalid")
)

Functions

func ChooseFile

func ChooseFile(options []language.Tag, fallback language.Tag, acceptLangHeader string) (string, error)

Choose which file to show from options based on the Language-Accept header. Fallback will be chosen when the Language-Accept header does not contain an available language.

The file name will be returned.

func HTTPError

func HTTPError(w http.ResponseWriter, code int)

Send an error to the HTTP client with the status text and code.

func ParseLanguageFiles

func ParseLanguageFiles(fsys fs.FS, folder string) ([]language.Tag, error)

Parse all the available languages of files in a folder.

Types

type Handler

type Handler func(w http.ResponseWriter, r *http.Request) error

A Handler is an http.HandlerFunc that can return an error.

func (Handler) ServeHTTP

func (fn Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

Implement the http.Handler interface.

type HandlerError

type HandlerError struct {
	Err  error
	Code int
}

A HandlerError contains information about an error that occured inside a Handler.

func NewHandlerError

func NewHandlerError(err error, code int) *HandlerError

Create a new HandlerError with error and code.

func (HandlerError) Error

func (e HandlerError) Error() string

type Server

type Server struct {
	*chi.Mux
	// contains filtered or unexported fields
}

A Server is a wrapper for an HTTP server that serves manuals from a filesystem.

The Chi library is used and is fully compatible with net/http.

func NewServer

func NewServer(fsys fs.FS, options ServerOptions) *Server

Create a new server that uses fsys as its filesystem to serve manuals.

type ServerOptions

type ServerOptions struct {
	FallbackLanguage language.Tag
}