You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<!-- prettier-ignore --> {{< hextra/feature-card title="What is Clace?" subtitle="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." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
27
+
<!-- prettier-ignore --> {{< hextra/feature-card title="What is Clace?" subtitle="Clace™ is an Apache-2.0 licensed application server for web apps. Clace enables easy and secure hosting and management of multiple web apps written in any language/framework. Clace is cross-platform (Linux/Windows/OSX) and provides a GitOps workflow for managing web apps." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
27
28
28
-
<!-- prettier-ignore --> {{< hextra/feature-card title="How does it work?" subtitle="Clace combines the functionality of a reverse proxy (programmable in Starlark) and a container orchestrator (using Docker or Podman) in a single lightweight binary. Start Clace server and ensure Docker or Podman is running. Apps can be installed directly from GitHub source repo. Clace builds the image and starts the container lazily, on the first API call." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
29
+
<!-- prettier-ignore --> {{< hextra/feature-card title="How does it work?" subtitle="Clace implements a language/framework agnostic application server. Clace combines the functionality of a reverse proxy and a container orchestrator (using Docker or Podman) in a single lightweight binary. Clace builds images and runs containers directly from GitHub source repo." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
29
30
30
-
<!-- prettier-ignore --> {{< hextra/feature-card title="What can it be used for?" subtitle="Clace can be used on a dev machine during web app development. The app can then be deployed on a shared Clace server, adding OAuth authentication as required. Apps are deployed directly from the git repo, no build step required. For example, Clace can be used to deploy multiple Streamlit apps on a server shared across a team, using GitOps for managing CI/CD." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
31
+
<!-- prettier-ignore --> {{< hextra/feature-card title="What can it be used for?" subtitle="Clace can be used during app development, handling all env setup with live reload. Apps can then be deployed on a Clace server, adding OAuth authentication. For example, Clace can be used to deploy multiple Flask/Streamlit/FastAPI apps on a server shared across a team, using GitOps for managing CI/CD." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
31
32
32
33
{{< /hextra/feature-grid >}}
33
34
<br>
@@ -53,28 +54,28 @@ layout: hextra-home
53
54
54
55
{{< hextra/feature-grid >}}
55
56
56
-
<!-- prettier-ignore --> {{< hextra/feature-card title="Container management" link="docs/quickstart/#containerized-applications" subtitle="Automatically build and and deploy containers, with Docker or Podman." icon="docker" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
57
+
<!-- prettier-ignore --> {{< hextra/feature-card title="Container management" link="docs/quickstart/#containerized-applications" subtitle="Automatically build and deploy containers, with Docker or Podman." icon="docker" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
57
58
58
59
<!-- prettier-ignore --> {{< hextra/feature-card title="GitOps Workflow" link="docs/quickstart/#lifecycle-with-git" subtitle="Blue-green (staged) deployments, versioning and preview environments with no infra to manage." icon="github" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
59
60
60
61
<!-- prettier-ignore --> {{< hextra/feature-card title="Hypermedia web apps" link="docs/app/routing/#html-route" subtitle="Fast and lightweight backend driven apps, minimal frontend complexity." icon="html5" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
61
62
62
63
<!-- prettier-ignore --> {{< hextra/feature-card title="No build step" link="docs/app/overview/#app-lifecycle" subtitle="Backend and frontend development with no build artifacts to manage, deploy directly from the source repo." icon="binary-off" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
63
64
64
-
<!-- prettier-ignore --> {{< hextra/feature-card title="Lazy App Initialization" link="docs/quickstart/#containerized-applications" subtitle="Apps are initialized lazily, on demand: scale down to zero automatically." icon="pause" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
65
+
<!-- prettier-ignore --> {{< hextra/feature-card title="Scale down to zero" link="docs/quickstart/#containerized-applications" subtitle="Apps are initialized lazily, on demand: scale down to zero automatically." icon="pause" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
65
66
66
-
<!-- prettier-ignore --> {{< hextra/feature-card title="Cross-platform support" link="docs/quickstart/#installation" subtitle="Clace runs on Linux, Windows and OSX, works with Docker and Podman" icon="globe-alt" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
67
+
<!-- prettier-ignore --> {{< hextra/feature-card title="Cross-platform" link="docs/quickstart/#installation" subtitle="Clace runs natively on Linux, Windows and OSX and works with Docker or Podman" icon="globe-alt" style="background: radial-gradient(ellipse at 50% 80%,rgba(102, 89, 186, 0.25),hsla(0,0%,100%,0));" >}}
67
68
68
69
{{< /hextra/feature-grid >}}
69
70
70
71
<br>
71
72
72
73
{{< hextra/feature-grid >}}
73
74
74
-
<!-- prettier-ignore --> {{< hextra/feature-card title="Comparison with other tools" subtitle="Other tools for simplifying containerized deployment are Linux specific. They are built on top of reverse proxies (Traefik/Nginx), using container labels for routing. They are built for prod deployment only, not for dev. Adding OAuth or access control are not easy with other solutions." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
75
+
<!-- prettier-ignore --> {{< hextra/feature-card title="Comparison with other tools" subtitle="Open source PaaS solutions are built on top of reverse proxies (Traefik/Nginx) and work on Linux only. They support prod deployment only, not use in dev. They aim to be a simplified Kubernetes, providing pre-packaged apps, including support for deploying stateful applications like databases. <br><br>Clace is simpler because it does not aim to be a PaaS solution. Compared to other AppServers, Clace supports all languages and does not require any code changes in the app. Running in containers gives better isolation across apps. Clace is a single binary and runs natively on all platforms." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
75
76
76
-
<!-- prettier-ignore --> {{< hextra/feature-card title="Comparison with cloud services" subtitle="Cloud services like Cloud Run simplify the deployment of containerized web apps. They run outside your existing infrastructure, making it difficult to talk to your existing systems. Clace provides a similar easy to use interface. Instead of doing this as a cloud service, Clace does this on your hardware." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
77
+
<!-- prettier-ignore --> {{< hextra/feature-card title="Comparison with cloud services" subtitle=" Google Cloud Run/AWS AppRunner allow easy deployment of containerized web apps. They run outside your existing infrastructure, making it difficult to talk to your existing systems. When deploying multiple small apps, cost can become a factor, especially when larger instances are required.<br><br>Clace provides a similar easy to use interface, including scale down to zero, on your own hardware. Hundred of apps can be hosted on a single Clace serve. Apps are lazy-initialized and scale down to zero when idle. Costs are fixed, there are no unexpected bills when API volume increases." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
77
78
78
-
<!-- prettier-ignore --> {{< hextra/feature-card title="How is Clace different?" subtitle="Clace is a single binary, cross-platform and can be used during development. Adding OAuth and access control and atomic updates across multiple apps is easy. Clace is built for the internal tools use-case, allowing for services to be deployed and shared across a team securely." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
79
+
<!-- prettier-ignore --> {{< hextra/feature-card title="How is Clace different?" subtitle="Clace provides a Cloud Run type experience on your hardware. Code and config changes are blue-green staged for deployment. Multiple apps can be updated atomically (all-or-nothing), no broken state after deployment failures. <br><br>Clace is built for the application management lifecycle across a team, not just the initial installation. Clace has OAuth support and security sand-boxing features which allow operations teams to easily manage applications through GitOps while allowing development teams to freely make code changes." style="background: radial-gradient(ellipse at 50% 80%,rgba(89, 67, 7, 0.15),hsla(0,0%,100%,0));" >}}
Copy file name to clipboardExpand all lines: content/docs/App/Overview.md
+7-5
Original file line number
Diff line number
Diff line change
@@ -7,16 +7,18 @@ summary: "Overview of the Clace application development model"
7
7
8
8
Clace supports deploying any type of app, in any language/framework, using containerized apps. Apps can also be built where the backend API is in the container but the UI is built using Clace. Clace UI applications implement a [Hypermedia driven approach](https://hypermedia.systems/hypermedia-reintroduction/) for developing web applications. Applications return HTML fragments as API response using [Go html templates](https://pkg.go.dev/html/template). The UI uses HTML enhanced with hypermedia controls using the [HTMX library](https://htmx.org/) to implement user interactions.
9
9
10
-
The backend API routes and dependencies like CSS library, JavaScript modules etc are configured using [Starlark](https://github.com/google/starlark-go/blob/master/doc/spec.md) configuration. Any custom API handling required is implemented in handler functions also written in Starlark. Starlark is a subset of python, optimized for application configuration usecases.
10
+
The backend API routes and dependencies like CSS library, JavaScript modules etc are configured using [Starlark](https://github.com/google/starlark-go/blob/master/doc/spec.md) configuration. Any custom API handling required is implemented in handler functions also written in Starlark. Starlark is a subset of python, optimized for application configuration use-cases.
11
11
12
12
## App Types
13
13
14
14
Clace apps can be of three types:
15
15
16
+
-**Containerized apps**: The whole app is implemented in a container, Clace proxies the container results. This uses the container and proxy plugins. No Starlark code is required for this.
16
17
-**Starlark apps**: These use the Clace plugins to implement the whole app. No containers are required for such apps.
17
-
-**Containerized apps**: The whole app is implemented in a container, Clace proxies the container results. This uses the container and proxy plugins.
18
18
-**Hybrid apps**: The backend APIs are implemented in a container. Clace is used to implement the Hypermedia based UI using Starlark handlers. This uses the http plugin to talk to the backend API and the container plugin to configure the backend.
19
19
20
+
This section of the docs covers Starlark and Hybrid apps. For a containerized app, the `--spec` definition includes all the app definition. There is no need to do any custom Starlark config for a regular containerized app.
21
+
20
22
## Structure
21
23
22
24
The structure of a Clace application is:
@@ -115,7 +117,7 @@ and an `~/myapp3/app.go.html` file containing
115
117
116
118
Run `clace app create --auth=none --dev ~/myapp3 /hello3 `. After that, the app is available at `/hello3`. Note that the `--dev` option is required for the `index_gen.go.html` file to be generated.
117
119
118
-
The name of the app is hello3. There is only one route defined, for page /, which shows a HTML page with the name of the app. The body is generated from the contents of the app.go.html file. A more verbose way to write the same app config would be
120
+
There is only one route defined, for page /, which shows a HTML page with the name of the app. The body is generated from the contents of the app.go.html file. A more verbose way to write the same app config would be
119
121
120
122
```python {filename="app.star"}
121
123
app = ace.app(name="hello3",
@@ -226,7 +228,7 @@ ensures that the specs are updated to the latest version. Periodically doing a g
226
228
227
229
## App Parameters
228
230
229
-
Having a file `params.star` in the app source code causes Clace to load the parameters definitions from that file. Parameters are environment value which can be specified during app creation. A sample param definition is
231
+
Having a file `params.star` in the app source code causes Clace to load the parameters definitions from that file. Parameters are environment values which can be specified during app creation. A sample param definition is
230
232
231
233
```python {filename="params.star"}
232
234
param("port", type=INT,
@@ -251,7 +253,7 @@ The parameters are available in the app Starlark code, through the `param` names
251
253
252
254
Params are set, during app creation using `app create --param port=9000` or using `param update port 9000 /myapp`. Set value to `-` to delete the param. Use `param list /myapp` to list the params.
253
255
254
-
For containerized apps, all params specified for the app (including ones not specified in `params.star` spec) are passed to the container at runtime as environment parameters. `CL_APP_PATH` is a special param passed to the container with the app installation path (without the domain name).
256
+
For containerized apps, all params specified for the app (including ones not specified in `params.star` spec) are passed to the container at runtime as environment parameters. `CL_APP_PATH` is a special param passed to the container with the app installation path (without the domain name).`PORT` is also set with the value of the port number the app is expected to bind to within the container.
A containerized app runs the backend APIs in a container. Clace builds the image and manages the container lifecycle. It is also possible to specific an image to use.
10
+
11
+
## App Specs
12
+
13
+
Clace app specs are defined at https://github.com/claceio/appspecs. Most specs use containers, the `proxy` spec is an exception.
14
+
15
+
## App Config
16
+
17
+
needs to have a `Containerfile` (or `Dockerfile`) to define how the image is built. The app definition can have
which completely specifies the app. This is saying that the app is using the container plugin to configure the container and the proxy plugin to proxy all API calls (`/` route) to the container url. On the first API call to the app, Clace will build the image, start the container and proxy the API traffic to the appropriate port. No other configuration is required in Starlark. If the container spec does not define the port being exposed, then the container config needs to specify the port number to use. The port number can be parameterized.
0 commit comments