clace

Hypermedia Driven Web Tools Platform

Menu

• Overview
• Features
  • Development Features
  • Deployment Features
• Roadmap
• Setup
  • Build from source
  • Initial Configuration
  • Start Service
  • Loading Apps
• Documentation
• Getting help
• Contributing

Overview

Clace is an Apache-2.0 licensed project building a platform to develop and deploy hypermedia driven web apps for internal tools. For running multiple web applications on a single machine, Clace provides functionality which usually requires stitching together multiple services: reverse proxy like nginx/caddy (for domain/path based routing, TLS certs, static file serving), application server like uwsgi/gunicorn with micro-framework like flask (for API handling) and deployment infrastructure like containers/VMs/k8s (for isolation across apps, versioning and staged deployments, gitops). For internal tools, Clace provides similar functionality in a single lightweight binary.

The project implements a server in Go and uses Starlark (a dialect of Python) for application configuration. The applications can call out to plugins implemented in Go. The plugin boundary (Starlark to Go) allows the specification of sandboxing rules which are enforced by the platform. As long as the application stays within the original rules, further application updates can be done without requiring any admin approval.

This repo hosts the source code for Clace server and client. The source for the documentation site clace.io is in the docs repo.

Features

Development Features

The development features supported currently by Clace are:

• Hypermedia driven backend API design, simplifying UI development.
• Automatic error handling support
• Dynamic reload using SSE (Server Sent Events) for all application changes, backend and frontend.
• Automatic creation of ECMAScript modules using esbuild.
• Automatic download for JavaScript and CSS dependencies.
• Support for TailwindCSS and DaisyUI watcher integration.
• Template caching and automatic reload on changes.

Deployment Features

The deployment features supported currently by Clace are:

• Backend app code runs in a security sandbox, with allowlist based permissions.
• No build step, the development artifacts are ready for production use.
• Support for github integration, apps being directly deployed from github code.
• Database backed file system, for atomic version updates and rollbacks.
• Zero downtime application updates.
• Support for application data persistance using SQLite
• OAuth and SSO based authentication
• Scalable backend, all performance critical code is in Go, only application handler code is in Starlark.
• Support for domain based and path based routing at the app level.
• Virtual filesystem with content hash based file names backed by SQLite database, enabling aggressive static content caching.
• Brotli compression for static artifacts, HTTP early hints support for performance.
• Automatic SSL certificate creation based on certmagic.
• Staging mode for app updates, to verify whether code and config changes work on prod before making them live.
• Preview app creation support, for trying out code changes.

Roadmap

Clace is early in its development. The feature roadmap for Clace is:

• All plugins are internal (built into Clace binary) currently. The plan is to move to an external plugin model, plugins being loaded dynamically using go-plugin.
• SQLite is used for metadata storage currently. Support for postgres and other systems is planned.
• Support for workflow jobs, which would have a form based interface with limited customizability, but with support for triggered and scheduled execution.
• UI interface for Clace admin operations.
• Record replay based automatic integration test creation. Record all responses at the plugin boundary and use that to replay integration test scenarios. This is speculative currently, depending on the how the external plugin model is implemented.
• Distributed agent model, where the Clace server does the initial routing but the actual application execution happens on remote worker nodes.

Setup

Build from source

To install a release build, follow steps in the installation docs.

To install from source:

• Ensure that a recent version of Go is available, version 1.21.0 or newer
• Checkout the Clace repo, cd to the checked out folder
• Build the clace binary and place in desired location, like $HOME

# Ensure go is in the $PATH
mkdir $HOME/clace_source && cd $HOME/clace_source
git clone -b main https://github.com/claceio/clace && cd clace
go build -o $HOME/clace ./cmd/clace/

Initial Configuration

To use the clace service, you need an initial config file with the service password and a work directory. The below instructions assume you are using $HOME/clhome/clace.toml as the config file and $HOME/clhome as the work directory location.

• Create the clhome directory
• Create the clace.toml file, and create a randomly generate password for the admin user account

export CL_HOME=$HOME/clhome && mkdir $CL_HOME
$HOME/clace password > $CL_HOME/clace.toml

This will print a random password on the screen, note that down as the password to use for accessing the applications.

Start Service

To start the service, the CL_HOME environment variable has to point to the work directory location and the CL_CONFIG_FILE env variable should point to the config file.

export CL_HOME=$HOME/clhome
export CL_CONFIG_FILE=$CL_HOME/clace.toml
$HOME/clace server start

Add the exports to your shell profile file. The service logs will be going to $CL_HOME/logs. To get the logs on the console also, you can add -c -l DEBUG to the server start command.

The service will be started on https://localhost:25223 by default (HTTP port 25222).

Loading Apps

To create an app, run the Clace client

$HOME/clace app create --approve /disk_usage $HOME/clace_source/clace/examples/disk_usage/

This will create an app at /disk_usage with the example disk_usage app. The disk_usage app provides a web interface for looking at file system disk usage, allowing the user to explore the sub-folders which are consuming most disk space.

To access the app, go to https://127.0.0.1:25223/disk_usage. Use admin as the username and use the password previously generated. Allow the browser to connect to the self-signed certificate page. Or connect to http://127.0.0.1:25222/disk_usage to avoid the certificate related warning.

Sample App

To create an app with a custom HTML page which shows a listing of files, create an directory ~/fileapp with file app.star file containing:

load("exec.in", "exec")

def handler(req):
   ret = exec.run("ls", ["-l"])
   if ret.error:
       return {"Error": ret.error, "Lines": []}
   return {"Error": "", "Lines": ret.value}

app = ace.app("File Listing",
              custom_layout=True,
              pages = [ace.page("/")],
              permissions = [ace.permission("exec.in", "run", ["ls"])]
             )

and file index.go.html containing:

<!doctype html>
<html>
  <head>
    <title>File List</title>
  </head>
  <body>
    <h1>File List</h1>
    {{ .Data.Error }}
    {{ range .Data.Lines }}
       {{.}}
       <br/>
    {{end}}
  </body>
</html>

Run clace app create --auth-type=none --approve /files ~/fileapp. The app is available at https://localhost:25223/files.

Documentation

Clace docs are at https://clace.io/docs/. For doc bugs, raise a GitHub issue in the docs repo.

Getting help

Please use Github Discussions for discussing Clace related topics. Please use the bug tracker only for bug reports and feature requests.

Contributing

PRs welcome for bug fixes. Commit messages should reference bugs.

For feature enhancements, please first file a ticket with the feature label and discuss the change before working on the code changes.

The Google go style guide is used for Clace. For application behavior related fixes, refer the app unit test cases. Those test run as part of regular unit tests go test ./.... For API related changes, Clace uses the commander-cli library for automated CLI tests. To run the CLI test, run CL_HOME=. tests/run_cli_tests.sh from the clace home directory.

Thanks for all contributions!