Skip to content

Commit eb2811e

Browse files
laurcilaurci
committed
apps docs
1 parent 4280d23 commit eb2811e

1 file changed

Lines changed: 387 additions & 2 deletions

File tree

‎docs/resources/apps.mdx‎

Lines changed: 387 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,396 @@
11
---
22
sidebar_position: 1
33
---
4+
import Mermaid from '@theme/Mermaid';
5+
import ResourceNameValidation from '../common/resource-name-validation.md';
46

57
# Apps
68

7-
:::note Work in Progress
9+
Apps provide a simplified way to deploy and manage applications on lttle.cloud by orchestrating a single machine with optional service exposure. They offer a streamlined developer experience by combining machine and service configuration into a single resource, automatically managing the underlying infrastructure.
810

9-
This section is a work in progress.
11+
Think of Apps as a convenient wrapper around machines that handles service creation and domain allocation for you, making it easier to deploy web applications and APIs.
12+
13+
If you want to know how to deploy an app, check [Building & Deploying > Building](../building-and-deploying/building.md) and [Building & Deploying > Deploying](../building-and-deploying/deploying.md).
14+
15+
## Configuration
16+
17+
| Properties | Type | Required | Default |
18+
| :-------------------------------------- | :---------------------------------: | :------: | :-------: |
19+
| `namespace` | `string` | | `default` |
20+
| [`name`](#name) | `string` | ✓ | |
21+
| [`tags`](#tags) | `array<string>` | | |
22+
| [`image`](#image) | `string` | ✓ | |
23+
| [`resources`](#resources) | `object` | ✓ | |
24+
| [`expose`](#expose) | `object` | | |
25+
| [`mode`](#mode) | `object` \| `regular` | | `regular` |
26+
| [`restart-policy`](#restart-policy) | `always` \| `on-failure` \| `never` | | `always` |
27+
| [`environment`](#environment-variables) | `object` | | |
28+
| [`volumes`](#volumes) | `array<object>` | | |
29+
| [`command`](#command) | `array<string>` | | |
30+
| [`depends-on`](#depends-on) | `array<object>` | | |
31+
32+
If you want to know more about namespaces, check [Building & Deploying > Namespaces](../building-and-deploying/namespaces.md)
33+
34+
### Name
35+
36+
The name is the unique identifier for your app within a namespace. It is used as the name for the underlying machine and to generate service names.
37+
38+
<ResourceNameValidation />
39+
40+
```yaml title="webapp.lttle.yaml"
41+
app:
42+
name: web-frontend
43+
```
44+
45+
### Tags
46+
47+
Tags are used to organize and categorize resources. They can be any valid UTF-8 string and can be used to filter resources in the [Web Console](../monitoring/web-console.md). Tags applied to the app are automatically inherited by the managed machine and services.
48+
49+
```yaml title="webapp.lttle.yaml"
50+
app:
51+
tags:
52+
- frontend
53+
- production
54+
- web
55+
```
56+
57+
### Image
58+
59+
The OCI-compliant container image to run. This can be any valid image from a container registry.
60+
61+
```yaml title="webapp.lttle.yaml"
62+
app:
63+
image: nginx:1.21
64+
```
65+
66+
### Resources
67+
68+
The compute resources allocated to the machine. This follows the same structure as [machine resources](./machines.mdx#resources).
69+
70+
| Properties | Type | Required |
71+
| :------------------ | :-------------------------------------- | :------: |
72+
| [`cpu`](#cpu) | `int` (min: `1` max: `24`) | ✓ |
73+
| [`memory`](#memory) | `int` mebibytes (min: `64` max: `1024`) | ✓ |
74+
75+
```yaml title="webapp.lttle.yaml"
76+
app:
77+
resources:
78+
cpu: 2
79+
memory: 512
80+
```
81+
82+
### Expose
83+
84+
The expose configuration defines how your app is made accessible through services. Each key in the expose object creates a separate service.
85+
86+
```yaml title="webapp.lttle.yaml"
87+
app:
88+
expose:
89+
web:
90+
port: 8080
91+
external:
92+
protocol: https
93+
api:
94+
port: 3000
95+
internal: {}
96+
```
97+
98+
Each expose entry has the following structure:
99+
100+
| Properties | Type | Required |
101+
| :-------------------------------------- | :---------------------------------: | :------: |
102+
| [`port`](#expose-port) | `int` | ✓ |
103+
| [`external`](#expose-external) | `object` | |
104+
| [`internal`](#expose-internal) | `object` | |
105+
| [`connection-tracking`](#connection-tracking) | `object` | |
106+
107+
:::info
108+
109+
Each expose entry must have either `external` or `internal` configured, but not both.
110+
111+
:::
112+
113+
#### Expose Port
114+
115+
The port number that your application listens on inside the container.
116+
117+
#### Expose External
118+
119+
Configuration for external (internet-facing) services:
120+
121+
| Properties | Type | Required | Default |
122+
| :---------- | :---------------------------------: | :------: | :-------: |
123+
| `protocol` | `http` \| `https` \| `tls` | ✓ | |
124+
| `host` | `string` | | *auto-generated* |
125+
| `port` | `int` | | *protocol default <br /> (or fallback on container port)* |
126+
127+
```yaml title="webapp.lttle.yaml"
128+
app:
129+
expose:
130+
web:
131+
port: 8080
132+
external:
133+
protocol: https
134+
host: myapp.example.com
135+
port: 443
136+
```
137+
138+
#### Expose Internal
139+
140+
Configuration for internal (tenant-only) services:
141+
142+
| Properties | Type | Required | Default |
143+
| :---------- | :---------------------------------: | :------: | :-----: |
144+
| `port` | `int` | | *container port* |
145+
146+
```yaml title="webapp.lttle.yaml"
147+
app:
148+
expose:
149+
api:
150+
port: 3000
151+
internal:
152+
port: 3000
153+
```
154+
155+
### Mode
156+
157+
The execution mode for the machine. This follows the same structure as [machine mode](./machines.mdx#mode).
158+
159+
```yaml title="webapp.lttle.yaml"
160+
app:
161+
mode: regular
162+
```
163+
164+
For flash mode configuration:
165+
166+
```yaml title="webapp.lttle.yaml"
167+
app:
168+
mode:
169+
flash:
170+
strategy: first-listen
171+
timeout: 300
172+
```
173+
174+
### Restart Policy
175+
176+
How the machine should behave when it exits. This follows the same options as [machine restart policy](./machines.mdx#restart-policy).
177+
178+
| Policy | Description |
179+
| ------------ | ----------------------------------------------------------------------- |
180+
| `always` | Always restart the machine if it exits |
181+
| `on-failure` | Restart the machine only if it exits with a non-zero exit code. |
182+
| `never` | Do not restart the machine if it exits event with a non-zero exit code. |
183+
184+
```yaml title="webapp.lttle.yaml"
185+
app:
186+
restart-policy: always
187+
```
188+
189+
### Environment Variables
190+
191+
Environment variables for the application. This follows the same structure as [machine environment](./machines.mdx#environment-variables).
192+
193+
```yaml title="webapp.lttle.yaml"
194+
app:
195+
environment:
196+
NODE_ENV: production
197+
API_URL: https://api.example.com
198+
PORT: "8080"
199+
```
200+
201+
### Volumes
202+
203+
Volume mounts for persistent storage. This follows the same structure as [machine volumes](./machines.mdx#volumes).
204+
205+
```yaml title="webapp.lttle.yaml"
206+
app:
207+
volumes:
208+
- name: app-data
209+
path: /data
210+
- name: logs
211+
path: /var/log/app
212+
```
213+
214+
### Command
215+
216+
The command to execute in the container. This follows the same structure as [machine command](./machines.mdx#command).
217+
218+
```yaml title="webapp.lttle.yaml"
219+
app:
220+
command:
221+
- node
222+
- server.js
223+
```
224+
225+
### Depends On
226+
227+
Dependencies on other machines. This follows the same structure as [machine dependencies](./machines.mdx#depends-on).
228+
229+
```yaml title="webapp.lttle.yaml"
230+
app:
231+
depends-on:
232+
- name: database
233+
- name: redis
234+
namespace: cache
235+
```
236+
237+
## Complete Example
238+
239+
Here's a complete example of an app configuration:
240+
241+
```yaml title="webapp.lttle.yaml"
242+
app:
243+
name: web-frontend
244+
namespace: production
245+
tags:
246+
- frontend
247+
- web
248+
image: nginx:1.21
249+
resources:
250+
cpu: 2
251+
memory: 512
252+
environment:
253+
NODE_ENV: production
254+
PORT: "8080"
255+
command:
256+
- nginx
257+
- -g
258+
- daemon off;
259+
mode: regular
260+
restart-policy: always
261+
expose:
262+
web:
263+
port: 8080
264+
external:
265+
protocol: https
266+
host: myapp.example.com
267+
api:
268+
port: 3000
269+
internal: {}
270+
volumes:
271+
- name: app-data
272+
path: /data
273+
depends-on:
274+
- name: database
275+
namespace: data
276+
```
277+
278+
## How Apps Work
279+
280+
Apps simplify application deployment by automatically managing machines and services for you. When you create an app, the controller:
281+
282+
1. **Creates a Machine**: Uses your app configuration to create a single machine with the specified image, resources, and settings
283+
2. **Generates Services**: For each entry in the `expose` configuration, creates a corresponding service to handle traffic routing
284+
3. **Manages Lifecycle**: Automatically updates the machine and services when you change the app configuration
285+
4. **Handles Cleanup**: When you delete the app, automatically removes the associated machine and services
286+
287+
### Machine Integration
288+
289+
The app controller creates a machine with the same name as the app, using these mappings:
290+
291+
- `app.image` → `machine.image`
292+
- `app.resources` → `machine.resources`
293+
- `app.environment` → `machine.environment`
294+
- `app.command` → `machine.command`
295+
- `app.volumes` → `machine.volumes`
296+
- `app.mode` → `machine.mode`
297+
- `app.restart-policy` → `machine.restart-policy`
298+
- `app.depends-on` → `machine.depends-on`
299+
- `app.tags` → `machine.tags` (with additional ownership tag)
300+
301+
### Service Generation
302+
303+
For each key in the `expose` configuration, the app controller creates a service named `{app-name}-{expose-key}`. For example:
304+
305+
```yaml
306+
app:
307+
name: my-app
308+
expose:
309+
web:
310+
port: 8080
311+
external:
312+
protocol: https
313+
api:
314+
port: 3000
315+
internal: {}
316+
```
317+
318+
This creates two services:
319+
- `my-app-web` (external HTTPS service)
320+
- `my-app-api` (internal service)
321+
322+
Both services target the `my-app` machine on their respective ports.
323+
324+
### Domain Allocation
325+
326+
For external services, if no `host` is specified, the system automatically generates a domain using the pattern:
327+
```
328+
{app-name}--{expose-key}--{tenant}.eu.lttle.host
329+
```
330+
331+
### Configuration Updates
332+
333+
When you update an app:
334+
- Machine configuration changes trigger a machine update (which may restart the machine depending on what changed)
335+
- Service configuration changes update the corresponding services
336+
- Adding/removing expose entries creates/deletes the corresponding services
337+
338+
## Best Practices
339+
340+
### Expose Configuration
341+
342+
Use descriptive names for your expose entries:
343+
344+
```yaml
345+
app:
346+
expose:
347+
web: # Main website
348+
port: 80
349+
external:
350+
protocol: https
351+
admin: # Admin interface
352+
port: 8080
353+
external:
354+
protocol: https
355+
host: admin.myapp.com
356+
metrics: # Internal metrics
357+
port: 9090
358+
```
359+
360+
### Resource Planning
361+
362+
Configure appropriate resources based on your application needs:
363+
364+
```yaml
365+
app:
366+
resources:
367+
cpu: 1 # 1 vCPU cores
368+
memory: 256 # 256MB RAM
369+
```
370+
371+
### Environment Management
372+
373+
Use environment variables to configure your application:
374+
375+
```yaml
376+
app:
377+
environment:
378+
NODE_ENV: production
379+
DATABASE_URL: postgresql://user:pass@db:5432/myapp
380+
REDIS_URL: redis://cache:6379
381+
```
382+
383+
### Health Considerations
384+
385+
Since apps create a single machine, ensure your application:
386+
387+
- Starts up reliably and quickly
388+
- Handles graceful shutdowns properly
389+
- Uses appropriate restart policies for your use case
390+
- Exposes health check endpoints when using flash mode
391+
392+
:::info
393+
394+
Apps are ideal for simple applications that don't require complex orchestration. For more advanced scenarios requiring multiple machines, custom networking, or complex dependencies, consider using machines and services directly.
10395

11396
:::

0 commit comments

Comments
 (0)