Skip to content

quick-start.md

Latest commit

 

History

History
108 lines (87 loc) · 3.2 KB

quick-start.md

File metadata and controls

108 lines (87 loc) · 3.2 KB

Quick Start Guide

Lactoserv is meant to be usable both as a standalone webserver application and as a framework for building higher-level applications that use web protocols for communication. This guide has a short "starter" example for each style. For more complete directions, please see the Configuration Guide and the Deployment Guide.

Standalone

These instructions are meant to get you up and running quickly. In a real deployment, you'll probably want to move the built application somewhere else (you can also make a tarball distro to unpack wherever is appropriate).

This example, in a slightly modified form, is available by running the script ./doc/quick-start/run-standalone, which will even build the system for you if you haven't done that yet.

Build the system:

$ git clone git@github.com:danfuzz/lactoserv
...
$ cd lactoserv
$ ./scripts/ubik dev build
...

Make a config file. In this case, we're serving a directory of static files located in the directory /usr/share/website, and responding to http://localhost:8080 and https://localhost:8443, the latter using a self-signed certificate.

$ cat >my-config.mjs <<EOF
import { StaticFiles } from '@lactoserv/webapp-builtins';

const config = {
  hosts: [{ hostnames: ['localhost'], selfSigned: true }],
  applications: [
    {
      name:          'mySite',
      class:         StaticFiles,
      siteDirectory: '/usr/share/website',
      etag:          true
    }
  ],
  endpoints: [
    {
      name:      'insecure',
      protocol:  'http',
      hostnames: ['*'],
      interface: '*:8080',
      mounts:    [{ application: 'mySite', at: '//*/' }]
    },
    {
      name:      'secure',
      protocol:  'http2',
      hostnames: ['*'],
      interface: '*:8443',
      mounts:    [{ application: 'mySite', at: '//*/' }]
    }
  ]
};

export default config;
EOF

Run the server. (If you don't want to see the debugging infodump, omit --log-to-stdout.)

$ ./out/lactoserv/bin/run --config=my-config.mjs --log-to-stdout

Browse! Use your web browser or curl to visit http://localhost:8080 or https://localhost:8443.

Framework

The framework example can be found in the directory quick-start/code.

This example can be run using the script ./doc/quick-start/run-standalone, which will even build the system for you if you haven't done that yet.

Compare and contrast

The differences between the configuration files of the standalone vs. the framework versions are:

  • The names of the modules that are imported from: In the standalone version, modules use the naming scope @lactoserv — the "published" name of the project — while the framework version uses the scope @this, which is the internal name used by the project to mean "this project's modules."
  • How the application is instantiated: In the standalone version, the configuration specifies a plain object which includes a class binding. In the framework version, the class StaticFiles is simply constructed with new.
Copyright 2022-2025 the Lactoserv Authors (Dan Bornstein et alia).
SPDX-License-Identifier: Apache-2.0