{"id":19939033,"url":"https://github.com/claceio/clace","last_synced_at":"2025-05-03T14:32:35.508Z","repository":{"id":157751543,"uuid":"627567877","full_name":"claceio/clace","owner":"claceio","description":"App deployment simplified. GitOps without the hassles. Application server for deploying internal tools for teams.","archived":false,"fork":false,"pushed_at":"2025-04-30T02:40:14.000Z","size":12644,"stargazers_count":593,"open_issues_count":1,"forks_count":11,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-30T03:32:53.992Z","etag":null,"topics":["application-server","appserver","containers","devops-tools","docker","golang","htmx","internal-tools","low-code-platform","self-hosted","starlark"],"latest_commit_sha":null,"homepage":"https://clace.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claceio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-04-13T18:29:51.000Z","updated_at":"2025-04-30T02:40:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"c552ade6-96d7-4257-b9e9-d7c7954d61da","html_url":"https://github.com/claceio/clace","commit_stats":null,"previous_names":[],"tags_count":95,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claceio%2Fclace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claceio%2Fclace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claceio%2Fclace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claceio%2Fclace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claceio","download_url":"https://codeload.github.com/claceio/clace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252203397,"owners_count":21710956,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-server","appserver","containers","devops-tools","docker","golang","htmx","internal-tools","low-code-platform","self-hosted","starlark"],"created_at":"2024-11-12T23:42:44.370Z","updated_at":"2025-05-03T14:32:35.501Z","avatar_url":"https://github.com/claceio.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://clace.io/clace.png\" alt=\"Clace-logo\" width=\"240\" /\u003e\n\n  \u003cp align=\"center\"\u003eApp deployment simplified, GitOps without the hassles.\u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/claceio/clace/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/claceio/clace\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/claceio/clace/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/claceio/clace.svg?color=00C200\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/claceio/clace/actions\"\u003e\u003cimg src=\"https://github.com/claceio/clace/workflows/CI/badge.svg\" alt=\"Build Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.codecov.io/github/claceio/clace\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/github/claceio/clace\" alt=\"Code Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/claceio/clace\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/claceio/clace\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/avelino/awesome-go\"\u003e\u003cimg src=\"https://awesome.re/mentioned-badge.svg\" alt=\"Mentioned in Awesome Go\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://landscape.cncf.io/?item=app-definition-and-development--application-definition-image-build--clace\"\u003e\u003cimg src=\"https://img.shields.io/badge/CNCF%20Landscape-0086FF\" alt=\"Listed in CNCF landscape\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n### Menu\n\n- [Overview](#overview)\n- [Features](#features)\n  - [Development Features](#development-features)\n  - [Deployment Features](#deployment-features)\n- [Roadmap](#roadmap)\n- [Setup](#setup)\n  - [Build from source](#build-from-source)\n  - [Initial Configuration](#initial-configuration)\n  - [Start Service](#start-service)\n  - [Loading Apps](#loading-apps)\n- [Documentation](#documentation)\n- [Getting help](#getting-help)\n- [Contributing](#contributing)\n\n## Overview\n\nClace is an Apache-2.0 licensed project building a web app development and deployment platform for internal tools. Clace allows you to deploy containerized apps and develop Hypermedia based web apps. Clace is cross-platform (Linux/Windows/OSX) and provides a GitOps workflow for managing web apps.\n\nClace apps are deployed directly from the git repo, no build step required. For example, Clace can be used to deploy Streamlit/Gradio apps, adding OAuth authentication for access control across a team.\n\nThis repo hosts the source code for Clace. The source for the documentation site [clace.io](https://clace.io) is in the [docs](https://github.com/claceio/docs) repo. App specifications, which are templates to create apps, are defined in the [appspecs](https://github.com/claceio/appspecs) repo. Sample apps are in the [apps](https://github.com/claceio/apps) repo.\n\n\u003cimg alt=\"Clace intro gif\" src=\"https://clace.io/intro_dark_small.gif\"/\u003e\n\n## Features\n\nClace can be used to:\n\n- Automatically generate a form based UI for backend [actions](https://clace.io/docs/actions/)\n- Deploy [containerized applications](https://clace.io/docs/container/overview/), Clace will build and manage the container lifecycle\n- Build and deploy custom [Hypermedia based applications](https://clace.io/docs/app/overview/) using Starlark (no containers required)\n\nClace supports the following for all apps:\n\n- [Declarative](https://clace.io/docs/applications/overview/#declarative-app-management) app deployment\n- Atomic updates (all or none) across [multiple apps](https://clace.io/docs/applications/overview/#glob-pattern)\n- [Staging mode](https://clace.io/docs/applications/lifecycle/#staging-apps) for app updates, to verify whether code and config changes work on prod before making them live.\n- [Preview app](https://clace.io/docs/applications/lifecycle/#preview-apps) creation support, for trying out code changes.\n- Support for [github integration](https://clace.io/docs/configuration/security/#private-repository-access), apps being directly deployed from github code.\n- OAuth and SSO based [authentication](https://clace.io/docs/configuration/authentication/#oauth-authentication)\n- Support for domain based and path based [routing](https://clace.io/docs/applications/routing/#request-routing) at the app level.\n- Integration with [secrets managers](https://clace.io/docs/configuration/secrets/), to securely access secrets.\n\nFor containerized apps, Clace supports:\n\n- Managing [image builds](https://clace.io/docs/quickstart/#containerized-applications), in dev and prod mode\n- Passing [parameters](https://clace.io/docs/develop/#app-parameters) for the container\n- Building apps from [spec](https://clace.io/docs/develop/#building-apps-from-spec), no code changes required in repo for [supported frameworks](https://github.com/claceio/appspecs) (Flask, Streamlit and repos having a Containerfile)\n- Support for [pausing](https://clace.io/docs/container/config/) app containers which are idle\n\nFor building Hypermedia based apps, Clace supports:\n\n- Automatic [error handling support](https://clace.io/docs/plugins/overview/#automatic-error-handling)\n- Automatic creation of ECMAScript modules using [esbuild](https://esbuild.github.io/).\n- Support for [TailwindCSS](https://tailwindcss.com/) and [DaisyUI](https://daisyui.com/) watcher integration.\n- [Automatic SSL](https://clace.io/docs/configuration/networking/#enable-automatic-signed-certificate) certificate creation based on [certmagic](https://github.com/caddyserver/certmagic).\n- Backend app code runs in a [security sandbox](https://clace.io/docs/applications/appsecurity/#security-model), with allowlist based permissions.\n- [No build step](https://clace.io/docs/develop/#app-lifecycle), the development artifacts are ready for production use.\n- Support for application data persistance using SQLite\n- Virtual filesystem with [content hash based file names](https://clace.io/docs/develop/templates/#static-function) backed by SQLite database, enabling aggressive static content caching.\n- Brotli compression for static artifacts, HTTP early hints support for performance.\n\n## Roadmap\n\nThe feature roadmap for Clace is:\n\n- SQLite is used for metadata storage currently. Support for postgres is planned. This will be used to allow for horizontal scaling.\n\n## Setup\n\n\n### Certs and Default password\n\nClace manages TLS cert using LetsEncrypt for prod environments. For dev environment, it is recommended to install [mkcert](https://github.com/FiloSottile/mkcert). Clace will automatically create local certs using mkcert if it is present. Install mkcert and run `mkcert -install` before starting Clace server. Installing Clace using brew will automatically install mkcert.\n\nFor container based apps, Docker or Podman or Orbstack should be installed and running on the machine. Clace automatically detects the container manager to use.\n\nClace uses an `admin` user account as the default authentication for accessing apps. A random password is generated for this account during initial Clace server installation. Note down this password for accessing apps.\n\n### Install Clace On OSX/Linux\n\nTo install on OSX/Linux, run\n\n```shell\ncurl -sSL https://clace.io/install.sh | sh\n```\nStart a new terminal (to get the updated env) and run `clace server start` to start the Clace service.\n\n### Brew Install\n\nTo install using brew, run\n\n```\nbrew tap claceio/homebrew-clace\nbrew install clace\nbrew services start clace\n```\n\n### Install On Windows\n\nTo install on Windows, run\n\n```\npowershell -Command \"iwr https://clace.io/install.ps1 -useb | iex\"\n```\n\nStart a new command window (to get the updated env) and run `clace server start` to start the Clace service.\n\n### Install Apps\n\nOnce Clace server is running, to install apps declaratively, open a new window and run\n\n```\nclace apply --approve github.com/claceio/clace/examples/utils.star all\n```\n\nTo install apps using the CLI, run\n\n```\nclace app create --approve github.com/claceio/apps/system/list_files /files\nclace app create --approve github.com/claceio/apps/system/disk_usage /disk_usage\nclace app create --approve github.com/claceio/apps/utils/bookmarks /book\n```\n\nOpen https://localhost:25223 to see the app listing. The disk usage app is available at https://localhost:25223/disk_usage (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, the list files app is available at https://localhost:25223/files. Add the `--auth none` flag to the `app create` command to disable authentication.\n\nSee [installation]({{\u003c ref \"installation\" \u003e}}) for details. See [config options]({{\u003c ref \"configuration\" \u003e}}) for configuration options. To enable Let's Encrypt certificates, see [Automatic SSL]({{\u003c ref \"configuration/networking/#enable-automatic-signed-certificate\" \u003e}}).\n\nThe release binaries are also available at [releases](https://github.com/claceio/clace/releases). See [install from source]({{\u003c ref \"installation/#install-from-source\" \u003e}}) to build from source.\n\n\nTo install a containerized app, ensure either Docker or Podman is running and run\n\n```\nclace app create --spec python-streamlit --branch master --approve github.com/streamlit/streamlit-example /streamlit\n```\n\nIf the source repo has a `Dockerfile` or `Containerfile`, run\n\n```\nclace app create --spec container --approve \u003csource_path\u003e /myapp\n```\n\nto install the app.\n\n### Build from source\n\nTo install a release build, follow steps in the [installation docs](https://clace.io/docs/installation/#install-release-build).\n\nTo install from source:\n\n- Ensure that a recent version of [Go](https://go.dev/doc/install) is available, version 1.21.0 or newer\n- Checkout the Clace repo, cd to the checked out folder\n- Build the clace binary and place in desired location, like $HOME\n\n```shell\n# Ensure go is in the $PATH\nmkdir $HOME/clace_source \u0026\u0026 cd $HOME/clace_source\ngit clone -b main https://github.com/claceio/clace \u0026\u0026 cd clace\nexport CL_HOME=$HOME/clhome \u0026\u0026 mkdir -p $CL_HOME/config\ngo build -o $CL_HOME/clace ./cmd/clace/\n```\n\n### Initial Configuration For Source Install\n\nTo 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.\n\n- Create the clhome directory\n- Create the clace.toml file, and create a randomly generate password for the **admin** user account\n\n```shell\ncd $CL_HOME\ngit clone -C config https://github.com/claceio/appspecs\n$CL_HOME/clace password \u003e $CL_HOME/clace.toml\n$CL_HOME/clace server start\n```\n\nThis will print a random password on the screen, note that down as the password to use for accessing the applications.\nThe service will be started on [https://localhost:25223](https://127.0.0.1:25223) by default (HTTP port 25222).\n\n### Loading Apps\n\nTo create an app, run the Clace client\n\n```shell\n$HOME/clace app create --approve $HOME/clace_source/clace/examples/disk_usage/ /disk_usage\n```\n\nThis 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.\n\nTo access the app, go to [https://127.0.0.1:25223/disk_usage](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](http://127.0.0.1:25222/disk_usage) to avoid the certificate related warning.\n\n## Sample App\n\nTo create an app with a custom HTML page which shows a listing of files, create an directory `~/fileapp` with file `app.star` file containing:\n\n```python\nload(\"exec.in\", \"exec\")\n\ndef handler(req):\n   ret = exec.run(\"ls\", [\"-l\"])\n   if ret.error:\n       return {\"Error\": ret.error, \"Lines\": []}\n   return {\"Error\": \"\", \"Lines\": ret.value}\n\napp = ace.app(\"File Listing\",\n              custom_layout=True,\n              routes = [ace.html(\"/\")],\n              permissions = [ace.permission(\"exec.in\", \"run\", [\"ls\"])]\n             )\n```\n\nand file `index.go.html` containing:\n\n\u003c!-- prettier-ignore --\u003e\n```html\n\u003c!doctype html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003eFile List\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003ch1\u003eFile List\u003c/h1\u003e\n    {{ .Data.Error }}\n    {{ range .Data.Lines }}\n       {{.}}\n       \u003cbr/\u003e\n    {{end}}\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003c!-- prettier-ignore-end --\u003e\n\nRun `clace app create --auth=none --approve ~/fileapp /files`. The app is available at `https://localhost:25223/files`.\n\n## Documentation\n\nClace docs are at https://clace.io/docs/. For doc bugs, raise a GitHub issue in the [docs](https://github.com/claceio/docs) repo.\n\n## Getting help\n\nPlease use [Github Discussions](https://github.com/claceio/clace/discussions) for discussing Clace related topics. Please use the bug tracker only for bug reports and feature requests.\n\n## Contributing\n\nPRs welcome for bug fixes. For feature enhancements, please first file a ticket with the `feature` label and discuss the change before working on the code changes.\n\nThe Google [go style guide](https://google.github.io/styleguide/go/guide) is used for Clace. For application behavior related fixes, refer the [app unit test cases](https://github.com/claceio/clace/tree/main/internal/app/tests). Those test run as part of regular unit tests `go test ./...`. For API related changes, Clace uses the [commander-cli](https://github.com/commander-cli/commander) library for [automated CLI tests](https://github.com/claceio/clace/tree/main/tests). To run the CLI test, run `gmake test` from the clace home directory.\n\nThanks for all contributions!\n\n\u003ca href=\"https://github.com/claceio/clace/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=claceio/clace\" /\u003e\n\u003c/a\u003e\n","funding_links":[],"categories":["Server Applications","Users","Tools"],"sub_categories":["HTTP Clients"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaceio%2Fclace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaceio%2Fclace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaceio%2Fclace/lists"}