search

claceio / clace

Webapp management for internal tools, app server for containerized apps
https://clace.io
Apache License 2.0
492 stars 9 forks source link
application-server appserver containers devops-tools docker golang htmx internal-applications internal-tools low-code-platform self-hosted starlark webapp

readme

Clace-logo

Webapp management for internal tools, app server for containerized apps

License Latest Release Build Status Code Coverage Go Report Card

Menu

Overview

Clace is an Apache-2.0 licensed project building a web app development and deployment platform for internal tools. Clace allows easy and secure hosting of multiple web apps, in any language/framework, on a single machine. Clace is cross-platform (Linux/Windows/OSX) and provides a GitOps workflow for managing web apps.

Clace combines the functionality of a reverse proxy, a hypermedia based micro-framework and a container orchestrator (using Docker or Podman) in a single lightweight binary. After starting the Clace server and ensuring Docker or Podman is running, new apps can be installed in one command from GitHub source repo. Clace builds the image and starts the container lazily, on the first API call. Clace can also automatically build simple form based UI for backend APIs.

Clace can be used to develop any containerized web app on a development machine and then deploy the app on a shared server. Apps are deployed directly from the git repo, no build step required. Clace can be used to deploy Streamlit apps, adding OAuth authentication for access control across a team.

This repo hosts the source code for Clace server and client. The source for the documentation site clace.io is in the docs repo. App specifications, which are templates to build apps, are defined in the appspecs repo.

Clace intro gif

Features

Clace can be used to:

Clace supports the following for all apps:

For containerized apps, Clace supports:

For building Hypermedia based apps, Clace supports:

Roadmap

The feature roadmap for Clace is:

Setup

Install

To install on OSX/Linux, run

curl -L https://clace.io/install.sh | sh
source $HOME/clhome/bin/clace.env
clace server start &

To install on Windows, run

pwsh -Command "iwr https://clace.io/install.ps1 -useb | iex"

Use powershell if pwsh is not available. Start a new command window (to get the updated ENV values) and run clace server start to start the service.

To install apps, run

clace app create --approve github.com/claceio/apps/system/disk_usage /disk_usage
clace app create --approve github.com/claceio/apps/utils/bookmarks /book

The disk usage app is available at https://localhost:25223/disk_usage (use port 25222 for HTTP). admin is the username, use the password printed by the install script. The bookmark manager is available at https://localhost:25223/book. Add --auth none to the app create command to disable auth.

To install a containerized app, ensure either Docker or Podman is running and run

clace app create --spec image --approve --param image=nginx --param port=80 - nginxapp.localhost:/
clace app create --spec python-streamlit --param app_file=hello --branch master --approve github.com/streamlit/streamlit-example /streamlit_hello

If the source repo has a Dockerfile or Containerfile, run

clace app create --spec container --approve <source_path> /myapp

to install the app.

Build from source

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

To install from source:

# 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 For Source Install

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.

export CL_HOME=$HOME/clhome && mkdir $CL_HOME
cd $CL_HOME
mkdir config
git clone -C config https://github.com/claceio/appspecs
$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.

export CL_HOME=$HOME/clhome
$HOME/clace server start

Add the exports to your shell profile file. The service logs will be going to $CL_HOME/logs.

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 $HOME/clace_source/clace/examples/disk_usage/ /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,
              routes = [ace.html("/")],
              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=none --approve ~/fileapp /files. 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!