Get started

Get started

Obtain laitos software

Download the latest laitos software from the releases page.

Alternatively, compile the software manually by cloning this repository and then run go build.

Craft your configuration

A configurable laitos component belongs to one of the three categories:

• Apps - reading news and Emails, make a Tweet, ask about weather, etc.
  • Some apps do not require manual configuration and they are pre-enabled.
• Daemons - web/mail/DNS servers, chat bots, etc. Many daemons are capable of accepting app command input and allow command execution protected by a password.
• Web services - HTML-based utilities, web-hooks for integration with 3rd party services, etc.

Follow the links in component list to craft your very own configuration in JSON.

As an example, here we use laitos DNS server to provide a safer and ad-free web experience at home, and enable a couple of web utilities:

{
  "DNSDaemon": {
    "AllowQueryFromCidrs": ["35.196.0.0/16", "37.228.0.0/16"]
  },
  "HTTPDaemon": {},
  "HTTPHandlers": {
    "CommandFormEndpoint": "/cmd",
    "FileUploadEndpoint": "/upload",
    "InformationEndpoint": "/info",
    "LatestRequestsInspectorEndpoint": "/latest_requests",
    "ProcessExplorerEndpoint": "/proc",
    "RequestInspectorEndpoint": "/myrequest",
    "WebProxyEndpoint": "/proxy"
  }
}

Start the program

Assume that latios software is in current directory, run the following command:

sudo ./laitos -config <PATH TO JSON FILE> -daemons <LIST>

Note that:

• Web, mail, and many other daemons usually bind to privileged ports, Run laitos using sudo to ensure their proper operation.
• Replace <PATH TO JSON FILE> by the relative or absolute path to your configuration file.
• Replace <LIST> by daemon names to start. Use comma to separate names (e.g.dnsd,smtpd,httpd). Here are the names:
  • dnsd - DNS server for ad-free and safer browsing experience
  • httpd - Web server secured by TLS certificate
  • insecurehttpd - Web server without TLS encryption
  • simpleipsvcd - Simple IP services that were popular in the nostalgia era of Internet
  • smtpd - Mail server that forwards all received Emails to your personal addresses
  • snmpd - Network management server that serves laitos program statistics
  • telegram - Telegram messenger chat bot that runs app commands
  • phonehome - Send telemetry reports of this computer to your laitos servers
  • plainsocket - Telnet-compatible server that runs app commands
  • maintenance - Automated server maintenance and program health report
• Apps are enabled automatically once they are configured in the JSON file. Some apps such as the RSS News Reader are automatically enabled via their built-in default configuration.

Other deployment techniques

Use environment variables to feed the program configuration

For ease of deployment, when LAITOS_CONFIG environment variable is not empty, laitos will load its configuration from there.

When LAITOS_INDEX_PAGE environment variable not empty, laitos will use its content for the index page served by HTTP daemon(s).

Check out environment variable usage examples in the Kubernetes example and the example in Dockerfile

Be aware that the combined size of all environment variables generally cannot exceed ~2MBytes.

Build a container image

The images of a (usually) up-to-date version of laitos are uploaded to Docker Hub hzgl/laitos.

If you wish to customise the image to your needs, feel free to use the Dockerfile from GitHub repository as a reference.

Check out the Kubernetes deployment example for a quick-start of hosting laitos on Kubernetes.

Deploy on cloud

laitos runs well on all popular cloud vendors, it supports cloud virtual machines for a straight-forward installation, as well as more advanced cloud features such as AWS Elastic Beanstalk and AWS Lambda (in combination with API gateway). Check out the cloud deployment tips.

Deploy on Windows

laitos is well optimised for running on Windows server and Windows desktop.

Instead of manually running laitos.exe in command prompt, check out this PowerShell script that helps to start laitos automatically in the background using Task Scheduler.

Advanced program behaviours

Self-healing

laitos is extremely reliable thanks to its many built-in mechanisms that make automated attempts to restart and isolate faulty components. The built-in mechanisms are fully automatic and do not require intervention:

1. Automatically recover from transient errors when contacting external resources, such as API services on the public Internet.
2. Every daemon automatically restarts in case of a transient initialisation error.
3. In the unlikely event of a program crash, the laitos program automatically restarts itself to recover.
4. In the extremely unlikely event of repeated program crashes in short succession (20 minutes), laitos will attempt to automatically isolate the faulty daemon by removing daemons before the next restart - shedding the heavier daemons (e.g. DNS) first before shedding the lighter daemons (e.g. HTTP daemon).

Optionally, laitos can send server owner a notification mail when a program crash occurs. To enable the notification, follow outgoing mail configuration and then specify Email recipients in program JSON configuration:

{
  ...

  "SupervisorNotificationRecipients": [
    "server-owner@hotmail.com"
  ],

  ...
}

Please use Github issues to report program crashes. Notification mail content and program output contain valuable clues for diagnosis - please retain them for an issue report.

More command line options

Use the following command line options with extra care:

Flag	Value data type	Meaning
-debug	true/false	Print stack traces to standard error upon receiving the interrupt signal SIGINT.
-gomaxprocs Num	Integer	Specify maximum number of concurrent goroutines. The default value is the number of CPU cores/threads.
-disableconflicts	true/false	Automatically stop and disable the following daemons that may interfere with laitos: apache web server bind DNS server systemd-resolved DNS proxy lighttpd web server postfix mail server sendmail mail server
-awslambda	true/false	Launch laitos as a handler for AWS Lambda function. See cloud deployment tips for the detailed usage.
-awsinteg	true/false	The master switch for turning on all points of integration with AWS infrastructure resources such as S3, SNS, SQS, Kinesis Firehose. See cloud deployment tips for the detailed usage.
-prominteg	true/false	The master switch for turning on all points of integration with prometheus metrics exporter. See Web service - prometheus metrics exporter for the detailed usage.
-profhttpport PORT	Integer	Start an HTTP server on localhost:PORT to serve program profiling data at URL location "/debug/pprof/{cmdline,profile,symbol,trace}".