### Run Homechart Server

Source: https://homechart.app/docs/references/cli

Start the Homechart server.

```bash
# Example usage for run command (no specific code provided in source)

```

--------------------------------

### Install Homechart via Helm

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Add the Homechart Helm repository and install the chart into a Kubernetes cluster.

```bash
helm repo add homechart https://helm.homechart.app/
helm install my-homechart homechart/homechart
```

--------------------------------

### Print Homechart Version

Source: https://homechart.app/docs/references/cli

Display the currently installed version of Homechart.

```bash
# Example usage for version command (no specific code provided in source)

```

--------------------------------

### Native Function: getOS()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getOS` native function to determine the operating system.

```APIDOC
## Native Function: getOS()

### Description
This example demonstrates the `getOS` native function, which returns a string identifying the operating system (e.g., 'linux', 'darwin', 'windows').

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getOS() = std.native('getOS')();

getOS()
```

### Response
#### Success Response (200)
- **os** (string) - The name of the operating system.

#### Response Example
```json
"linux"
```
```

--------------------------------

### Native Function: getPath()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getPath` native function to get the current working directory.

```APIDOC
## Native Function: getPath()

### Description
This example shows the `getPath` native function, which returns the current working directory path as a string.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getPath() = std.native('getPath')();

getPath()
```

### Response
#### Success Response (200)
- **path** (string) - The current working directory path.

#### Response Example
```json
"/home/user/app"
```
```

--------------------------------

### Native Function: get()

Source: https://homechart.app/docs/references/jsonnet

Example usage of the `get` native function, which retrieves a value from an object using jq filtering with caching.

```APIDOC
## Native Function: get()

### Description
This example demonstrates the `get` native function, which retrieves a value from an object using jq filtering. It supports a `default` value and caching.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local get() = std.native('get')(object=null, field, default=null, prefix='');

get(object={
  a: 'b',
}, field='a', default='a', prefix='b')
```

### Response
#### Success Response (200)
- **value** (any) - The retrieved value or the default value if not found.

#### Response Example
```json
"b"
```
```

--------------------------------

### Jsonnet Format Example

Source: https://homechart.app/docs/references/jsonnet

Demonstrates the similarity between Jsonnet and JSON syntax, showing how to define objects and nested structures.

```APIDOC
## Jsonnet Format Example

### Description
This example illustrates the basic syntax of Jsonnet, which closely resembles JSON, and shows a simple object definition.

### Request Example
```jsonnet
{
  person1: {
    name: 'Alice',
    welcome: 'Hello ' + self.name + '!',
  },
  person2: self.person1 { name: 'Bob' },
}
```

### Response Example
```json
{
  "person1": {
    "name": "Alice",
    "welcome": "Hello Alice!"
  },
  "person2": {
    "name": "Bob",
    "welcome": "Hello Bob!"
  }
}
```
```

--------------------------------

### Native Function: getArch()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getArch` native function to retrieve the current system architecture.

```APIDOC
## Native Function: getArch()

### Description
This example shows how to use the `getArch` native function to obtain the system's architecture (e.g., 'amd64', 'arm64').

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getArch() = std.native('getArch')();

getArch()
```

### Response
#### Success Response (200)
- **architecture** (string) - The GOARCH string representing the system architecture.

#### Response Example
```json
"amd64"
```
```

--------------------------------

### YAML Translation Syntax Example

Source: https://homechart.app/docs/references/translations

This is an example of the YAML8n syntax used for defining translations in Homechart. It shows how to structure translation keys, provide context, and specify translations for different languages.

```yaml
translations: # A list of translation objects.  The objects contain context and a translation for each of the iso639codes
  EmailEmailAddressChangeConfirmationSubject:
    context: Subject for email address changes
    de: '[Aktion erforderlich] Bestätigen Sie Ihre aktualisierte E-Mail-Adresse'
    en: |
      [Action Required] Verify Your Updated Email Address
```

--------------------------------

### Native Function: getFile()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getFile` native function to read the content of a file.

```APIDOC
## Native Function: getFile()

### Description
This example shows the `getFile` native function, which reads the content of a specified file. It supports a fallback value if the file cannot be read.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getFile(path, fallback=null) = std.native('getFile')(path, fallback);

getFile('config.yaml', null)
```

### Response
#### Success Response (200)
- **content** (string) - The content of the file.

#### Response Example
```json
"key: value\nlist:\n  - item1\n  - item2"
```
```

--------------------------------

### Native Function: getEnv()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getEnv` native function to retrieve the value of an environment variable.

```APIDOC
## Native Function: getEnv()

### Description
This example demonstrates the `getEnv` native function, which retrieves the value of a specified environment variable. It allows for a fallback value if the variable is not set.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getEnv(key) = std.native('getEnv')(key);

getEnv('PWD')
```

### Response
#### Success Response (200)
- **value** (string) - The value of the environment variable, or an empty string/fallback if not found.

#### Response Example
```json
"/home/user/project"
```
```

--------------------------------

### Native Function: getConfig()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getConfig` native function to access the application's configuration object.

```APIDOC
## Native Function: getConfig()

### Description
This example demonstrates the `getConfig` native function, which returns the current application configuration as a Jsonnet object.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getConfig() = std.native('getConfig')();

config()
```

### Response
#### Success Response (200)
- **config** (object) - The application's configuration object.

#### Response Example
```json
{
  "setting1": "value1",
  "setting2": 123
}
```
```

--------------------------------

### Native Function: getCmd()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getCmd` native function to execute a shell command and retrieve its output.

```APIDOC
## Native Function: getCmd()

### Description
This example shows how to use the `getCmd` native function to execute an external command and capture its standard output. It supports a fallback value in case of errors.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getCmd(command, fallback=null) = std.native('getCmd')(command, fallback);

getCmd('ls -al mydir/', 'mydir')
```

### Response
#### Success Response (200)
- **output** (string) - The standard output of the executed command.

#### Response Example
```json
"total 8\n-rw-r--r-- 1 user group 1024 Jan 1 10:00 file1.txt\n-rw-r--r-- 1 user group 1024 Jan 1 10:00 file2.txt"
```
```

--------------------------------

### Define a CLI Macro

Source: https://homechart.app/docs/references/config

Example structure for defining a custom CLI macro with required arguments, flags, and a template.

```json
{
  "cli": {
    "macro": {
      "mymacro": {
        "argumentsRequired": [
          "argument1"
        ],
        "flags": {
          "d": {
            "usage": "D flag usage!"
          },
        },
        "template": "config",
        "usage": "Mymacro usage!",
      }
    }
  }
}
```

--------------------------------

### Traefik Command Line Arguments

Source: https://homechart.app/docs/guides/sso

Starts the Traefik proxy with HTTPS enabled on port 8443 and specifies the dynamic configuration file. Ensure the `traefik-dynamic.yaml` file is in the same directory or provide the correct path.

```bash
./traefik --entrypoints.https=true --entrypoints.https.address=:8443 --providers.file.filename=traefik-dynamic.yaml
```

--------------------------------

### Homechart Command Line Execution

Source: https://homechart.app/docs/guides/sso

Starts the Homechart application, configuring it to use specific proxy headers for user identification and setting the proxy address. The `-c config.json` flag specifies the configuration file.

```bash
homechart_app_proxyAddress=[::1] homechart_app_proxyHeaderEmail=Remote-Email homechart_app_proxyHeaderName=Remote-Name ./homechart_linux_amd64 -c config.json serve
```

--------------------------------

### Native Function: render()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `render` native function to process a string, potentially applying templates or transformations.

```APIDOC
## Native Function: render()

### Description
This example shows the `render` native function, which takes a string as input and returns a Jsonnet object, potentially after applying some rendering or templating logic.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local render(string) = std.native('render')(string);

render('{\n  "key": "value"\n}')
```

### Response
#### Success Response (200)
- **rendered_object** (object) - The Jsonnet object resulting from rendering the input string.

#### Response Example
```json
{
  "key": "value"
}
```
```

--------------------------------

### Native Function: getRecord()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `getRecord` native function to retrieve records of a specific type and name.

```APIDOC
## Native Function: getRecord()

### Description
This example demonstrates the `getRecord` native function, which retrieves a list of strings representing records of a given type and name. It supports a fallback value.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);

getRecord('users', 'admins', null)
```

### Response
#### Success Response (200)
- **records** (array) - An array of strings, where each string is a record identifier.

#### Response Example
```json
["admin1", "admin2"]
```
```

--------------------------------

### Using Native get Function

Source: https://homechart.app/docs/references/jsonnet

Retrieves values using jq filtering with optional caching and prefixing.

```jsonnet
local get() = std.native('get')(object=null, field, default=null, prefix='');

get(object={
  a: 'b',
}, field='a', default='a', prefix='b')
```

--------------------------------

### Native Function: regexMatch()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `regexMatch` native function to check if a string matches a regular expression.

```APIDOC
## Native Function: regexMatch()

### Description
This example demonstrates the `regexMatch` native function, which checks if a given string conforms to a specified regular expression pattern.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local regexMatch(regex, string) = std.native('regexMatch')(regex, string);

regexMatch('^\d+$', '12345')
```

### Response
#### Success Response (200)
- **match** (bool) - `true` if the string matches the regex, `false` otherwise.

#### Response Example
```json
true
```
```

--------------------------------

### Native Function: randStr()

Source: https://homechart.app/docs/references/jsonnet

Example of using the `randStr` native function to generate a random string of a specified length.

```APIDOC
## Native Function: randStr()

### Description
This example shows the `randStr` native function, which generates a random string of a specified length using alphanumeric characters.

### Method
Native Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```jsonnet
local randStr(length) = std.native('randStr')(length);

randStr(10)
```

### Response
#### Success Response (200)
- **random_string** (string) - A randomly generated string of the specified length.

#### Response Example
```json
"aBcDeFgHiJ"
```
```

--------------------------------

### Immutable Objects Example

Source: https://homechart.app/docs/references/jsonnet

Illustrates how to handle updates to Jsonnet values, emphasizing their immutable nature by creating new objects.

```APIDOC
## Immutable Objects Example

### Description
This example shows how to modify an object in Jsonnet by creating a new object that inherits from the original and overrides specific fields, reflecting the language's immutability.

### Request Example
```jsonnet
local object1 = {
  hello: 'world'
}

object1 + {
  hello: 'person'
}
```

### Response Example
```json
{
  "hello": "person"
}
```
```

--------------------------------

### Define Jsonnet Objects

Source: https://homechart.app/docs/references/jsonnet

Example of defining objects and using self-referencing fields in Jsonnet compared to the resulting JSON output.

```jsonnet
{
  person1: {
    name: 'Alice',
    welcome: 'Hello ' + self.name + '!',
  },
  person2: self.person1 { name: 'Bob' },
}
```

```json
{
  "person1": {
    "name": "Alice",
    "welcome": "Hello Alice!"
  },
  "person2": {
    "name": "Bob",
    "welcome": "Hello Bob!"
  }
}
```

--------------------------------

### Example OIDC Identity Token

Source: https://homechart.app/docs/guides/sso

A sample JSON structure representing the user details exposed by Homechart to OIDC applications.

```json
{
  "email": "jennifer@no-email.example.com",
  "email_verified": true,
  "locale": "en",
  "name": "Jennifer",
  "permissions": {
    "auth": 1,
    "bookmarks": 2,
    "budget": 2,
    "calendar": 2,
    "cook": 2,
    "health": 0,
    "inventory": 2,
    "notes": 2,
    "plan": 2,
    "reward": 2,
    "secrets": 2,
    "shop": 2
  },
  "permissions_labels": {
    "Kids - Edit": 0,
    "Kids - None": 2,
    "Kids - View": 1
  },
  "updated_at": "2025-10-22T18:58:51.643851Z"
}
```

--------------------------------

### Open Documentation Website

Source: https://homechart.app/docs/references/cli

Launch a web browser to the Homechart documentation website.

```bash
# Example usage for docs command (no specific code provided in source)

```

--------------------------------

### Run Homechart with Podman

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Deploy a Homechart container using Podman with a specific database connection string.

```bash
podman run -e homechart_database_uri=postgresql://homechart:homechart@postgresql/homechart -p 3000:3000 -d ghcr.io/candiddev/homechart:latest
```

--------------------------------

### Show Current Configuration

Source: https://homechart.app/docs/references/cli

Print the active configuration settings in JSON or YAML format.

```bash
# Example usage for show-config command (no specific code provided in source)

```

--------------------------------

### Ternary Operator Example

Source: https://homechart.app/docs/references/jsonnet

Demonstrates the use of the ternary operator for conditional value assignment in Jsonnet.

```APIDOC
## Ternary Operator Example

### Description
This example shows the usage of the ternary operator for conditional assignment of values in Jsonnet.

### Request Example
```jsonnet
local something = if true then 'else' else 'other';
```

### Response Example
```json
"else"
```
```

--------------------------------

### Run Homechart with Docker

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Deploy a standalone Homechart container with a PostgreSQL database URI.

```bash
docker run -e 'homechart_database_uri=postgresql://postgres:postgres@postgres/postgres' -p 3000:3000 -d ghcr.io/candiddev/homechart:latest
```

--------------------------------

### Show Rendered Configuration

Source: https://homechart.app/docs/references/cli

Display the final configuration after merging settings from files, environment variables, and command-line arguments.

```bash
# Example usage for config command (no specific code provided in source)

```

--------------------------------

### Authelia Command Line Execution

Source: https://homechart.app/docs/guides/sso

Launches the Authelia authentication server using the specified configuration file. Ensure the binary path and config file name are correct for your environment.

```bash
./authelia-linux-amd64 --config authelia.yaml
```

--------------------------------

### Use Dynamic Jsonnet for Configuration

Source: https://homechart.app/docs/references/config

Leverage Jsonnet functions to dynamically fetch or compute configuration values at startup.

```jsonnet
local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);
local level = getRecord('txt', 'level.candid.dev');

{
  cli: [
    logLevel: level,
  ],
}
```

--------------------------------

### Configure PostgreSQL for Homechart

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Commands to create the database and role required for Homechart. Replace placeholders with your specific credentials.

```sql
CREATE DATABASE homechart;
CREATE ROLE "homechart" WITH CREATEDB LOGIN PASSWORD 'homechart';
REVOKE ALL PRIVILEGES ON SCHEMA public FROM public;
GRANT ALL PRIVILEGES ON DATABASE homechart TO "homechart";
GRANT ALL PRIVILEGES ON SCHEMA public TO "homechart";
```

--------------------------------

### Importing Jsonnet Files

Source: https://homechart.app/docs/references/jsonnet

Demonstrates importing a library file and using a function defined within it.

```jsonnet
local func = import 'func.libsonnet';

{
  person1: {
    name: 'Alice',
    welcome: 'Hello ' + self.name + '!',
  },
  person2: func('Bob'),
}
```

```jsonnet
function(name)
  {
    name: name,
    welcome: 'Hello ' + self.name + '!',
  }
```

--------------------------------

### getOS

Source: https://homechart.app/docs/references/jsonnet

Returns the current operating system architecture based on GOOS.

```APIDOC
## getOS() string

### Description
This function returns the current architecture based on GOOS.

### Method
GET

### Endpoint
`/api/os`

### Response
#### Success Response (200)
- **architecture** (string) - The operating system architecture (e.g., 'linux', 'windows', 'darwin').

### Response Example
```json
{
  "architecture": "linux"
}
```
```

--------------------------------

### Deploy Homechart with Docker Compose

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Define and run Homechart and PostgreSQL services using a docker-compose.yml file.

```yaml
version: "3"
services:
  homechart:
    depends_on:
      - postgres
    environment:
      homechart_database_uri: postgresql://postgres:postgres@postgres/postgres
    image: ghcr.io/candiddev/homechart:latest
    ports:
      - "3000:3000"
    restart: always
  postgres:
    environment:
      POSTGRES_PASSWORD: postgres
    image: docker.io/postgres:16
    restart: always
    volumes:
      - postgres:/var/lib/postgresql/data
volumes:
  postgres: {}
```

--------------------------------

### Seed Database with Mock Data

Source: https://homechart.app/docs/references/cli

Populate the database with mock data and save the output as a JSON file to a specified path.

```bash
# Example usage for seed command (no specific code provided in source)

```

--------------------------------

### View End User License Agreement

Source: https://homechart.app/docs/references/cli

Display the Homechart End User License Agreement (EULA).

```bash
# Example usage for eula command (no specific code provided in source)

```

--------------------------------

### Download and Verify Homechart Binaries

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Commands to download, extract, and verify the integrity of Homechart binaries for different operating systems and architectures.

```bash
curl -L https://homechart.app/releases/homechart_darwin_amd64.gz | gzip -d > homechart
chmod +x homechart
sha256sum homechart | grep $(curl -L https://homechart.app/releases/homechart_darwin_amd64.sha256)
```

```bash
curl -L https://homechart.app/releases/homechart_darwin_arm64.gz | gzip -d > homechart
chmod +x homechart
sha256sum homechart | grep $(curl -L https://homechart.app/releases/homechart_darwin_arm64.sha256)
```

```bash
curl -L https://homechart.app/releases/homechart_linux_amd64.gz | gzip -d > homechart
chmod +x homechart
sha256sum homechart | grep $(curl -L https://homechart.app/releases/homechart_linux_amd64.sha256)
```

```bash
curl -L https://homechart.app/releases/homechart_linux_arm.gz | gzip -d > homechart
chmod +x homechart
sha256sum homechart | grep $(curl -L https://homechart.app/releases/homechart_linux_arm.sha256)
```

```bash
curl -L https://homechart.app/releases/homechart_linux_arm64.gz | gzip -d > homechart
chmod +x homechart
sha256sum homechart | grep $(curl -L https://homechart.app/releases/homechart_linux_arm64.sha256)
```

```bash
curl -L https://homechart.app/releases/homechart_windows_amd64.gz | gzip -d > homechart
chmod +x homechart
sha256sum homechart | grep $(curl -L https://homechart.app/releases/homechart_windows_amd64.sha256)
```

--------------------------------

### getFile

Source: https://homechart.app/docs/references/jsonnet

Retrieves the string value of a path, supporting local and HTTP/HTTPS GET requests with caching. Fallback values can be provided for error handling. HTTP/HTTPS requests can include custom headers.

```APIDOC
## getFile(path, fallback=null, cache=false) string

### Description
This function returns the string value of a `path` (local or http/https via GET). The results are cached for repeat lookups within the current render cycle. For HTTP or HTTPS paths, you can set headers for your request using a `#`, the header as a `k:v`, and delimited by a newline `\r\n`, e.g. `getEnv('https://example.com/api#myHeader:myValue\r\nmyOtherHeader:myOtherValue')`.
If the path is unreachable, an error will be thrown and rendering will halt. You can optionally provide a fallback value to prevent this, this value will be returned instead on failure.
The HTTP client used by getFile can be configured with `httpClient`. CA certificates can be added, and TLS can be disabled.
Using this function with URLs is disabled by default. Set `jsonnet_disableGetFileHTTP` to `false` to enable it.

### Parameters
#### Path Parameters
- **path** (string) - Required - The path to the file or URL.
- **fallback** (string) - Optional - A fallback value to return if the path is unreachable.
- **cache** (boolean) - Optional - Whether to cache the results for repeat lookups.

### Request Example
```json
{
  "path": "~/.bashrc",
  "fallback": "default_content"
}
```

### Response Example
```json
{
  "content": "string content of the file"
}
```
```

--------------------------------

### Retrieve Operating System

Source: https://homechart.app/docs/references/jsonnet

Returns the current architecture based on GOOS.

```jsonnet
local getOS() = std.native('getOS')();

getOS()
```

--------------------------------

### Importing Jsonnet Files

Source: https://homechart.app/docs/references/jsonnet

Shows how to import external Jsonnet files, enabling modularity and code reuse in configuration.

```APIDOC
## Importing Jsonnet Files

### Description
This example demonstrates how to import and utilize functions or data from another Jsonnet file (`.libsonnet`), promoting modular design.

### Request Example
```jsonnet
local func = import 'func.libsonnet';

{
  person1: {
    name: 'Alice',
    welcome: 'Hello ' + self.name + '!',
  },
  person2: func('Bob'),
}
```

### Response Example
```json
{
  "person1": {
    "name": "Alice",
    "welcome": "Hello Alice!"
  },
  "person2": {
    "name": "Bob",
    "welcome": "Hello Bob!"
  }
}
```
```

--------------------------------

### Wrap If Statements

Source: https://homechart.app/docs/references/jsonnet

Demonstrates the recommended practice of wrapping if-else expressions in parentheses for clarity.

```jsonnet
local noWrap = if 'this' then 'that' else 'that' + 'yep'
local withWrap = (if 'this' then 'that' else 'that') + 'yep'
```

--------------------------------

### Best Practices

Source: https://homechart.app/docs/references/jsonnet

Guidelines for writing clear and maintainable Jsonnet code, including wrapping conditional statements and formatting conventions.

```APIDOC
## Best Practices

### Always Wrap Your Ifs
`if`s can be wrapped with parenthesis in Jsonnet or not wrapped. By keeping `if`s always wrapped, it makes it easier to understand where they end:
```jsonnet
local noWrap = if 'this' then 'that' else 'that' + 'yep'
local withWrap = (if 'this' then 'that' else 'that') + 'yep'
```

### Formatting
“Proper” Jsonnet format/linting recommends:
  * Single quotes for strings
  * Two spaces, no tabs
```

--------------------------------

### Retrieving Application Configuration

Source: https://homechart.app/docs/references/jsonnet

Returns the current application configuration as a Jsonnet object.

```jsonnet
local getConfig() = std.native('getConfig')();

config()
```

--------------------------------

### Configure Google OIDC in Homechart

Source: https://homechart.app/docs/guides/sso

Add Google as an OIDC issuer by providing your generated Client ID and Client Secret. The redirect URL should be your Homechart instance's base URL followed by /oidc.

```json
{
  "oidc": {
    "google": {
      "clientID": "<client ID you copied from Google>",
      "clientSecret": "<client secret you copied from Google>",
      "displayName": "Google",
      "oidcIssuerURL": "https://accounts.google.com"
    }
  }
}
```

--------------------------------

### Homechart CLI Arguments

Source: https://homechart.app/docs/references/cli

Global arguments that must be provided before any command to configure the CLI behavior.

```APIDOC
## CLI Arguments

### Description
Global arguments used to configure the Homechart CLI environment. These must be placed before the command.

### Parameters
- **-c [path]** (string) - Optional - Path to the JSON/Jsonnet configuration file.
- **-f [format]** (string) - Optional - Set log format (human, kv, raw, default: human).
- **-l [level]** (string) - Optional - Set minimum log level (none, debug, info, error, default: info).
- **-p** (boolean) - Optional - Disable paging via less.
- **-s [status]** (string) - Optional - Set the minimum status for error message logging.
- **-x [key=value]** (string) - Optional - Set config key=value (can be provided multiple times).
```

--------------------------------

### Homechart CLI Commands

Source: https://homechart.app/docs/references/cli

List of available commands for the Homechart CLI, including server management and utility functions.

```APIDOC
## CLI Commands

### Description
Commands used to interact with the Homechart application. Commands support partial matching.

### Commands
- **autocomplete** - Adds autocomplete for Homechart commands into your terminal.
- **config** - Show the rendered config from all sources.
- **docs** - Open a web browser to the documentation website.
- **eula** - View the Homechart End User License Agreement (EULA).
- **generate-vapid** - Generate a private and public key for use with Web Push.
- **run** - Run Homechart server.
- **seed [output path]** - Seed the database with mock data and save the output to JSON.
- **show-config** - Print the current configuration as JSON or YAML.
- **tasks-*** - Manually run background maintenance tasks.
- **version** - Print the current version of Homechart.
```

--------------------------------

### Retrieving Architecture Information

Source: https://homechart.app/docs/references/jsonnet

Returns the current system architecture based on GOARCH.

```jsonnet
local getArch() = std.native('getArch')();

getArch()
```

--------------------------------

### Retrieve File Content

Source: https://homechart.app/docs/references/jsonnet

Fetches content from a local path or URL. Requires enabling HTTP access via configuration.

```jsonnet
local getFile(path, fallback=null) = std.native('getFile')(path, fallback);

getFile('~/.bashrc', 'fallback')
```

--------------------------------

### render

Source: https://homechart.app/docs/references/jsonnet

Renders a given string using Jsonnet.

```APIDOC
## render(string) object

### Description
This function renders `string` using Jsonnet.

### Parameters
#### Request Body
- **jsonnetString** (string) - Required - The Jsonnet string to render.

### Request Example
```json
{
  "jsonnetString": "{\"message\": \"Hello, Jsonnet!\"}"
}
```

### Response Example
```json
{
  "renderedObject": {
    "message": "Hello, Jsonnet!"
  }
}
```
```

--------------------------------

### CalDAV Supported Methods

Source: https://homechart.app/docs/guides/calendar

Lists the specific URLs and methods supported by Homechart for CalDAV integration. Ensure your CalDAV client adheres to these specifications.

```text
PROPFIND /dav/calendars
PROPFIND /dav/calendars/{calendarID}/
REPORT /dav/calendars/{calendarID}/
  Supported Report Sets:
    - calendar-query
    - calendar-multiget
    - sync-collection
DELETE /dav/calendars/{calendarID}/{itemID}
PUT /dav/calendars/{calendarID}/{itemID}
PROPFIND /dav/principals/
PROPFIND /dav/principals/{principalID}/

```

--------------------------------

### Manually Run Maintenance Tasks

Source: https://homechart.app/docs/references/cli

Execute background maintenance tasks on demand.

```bash
# Example usage for tasks-* command (no specific code provided in source)

```

--------------------------------

### Configure Microsoft OIDC in Homechart

Source: https://homechart.app/docs/guides/sso

Integrate Microsoft as an OIDC provider by entering your Client ID and Client Secret. The authorized redirect URL is your Homechart instance base URL followed by /oidc.

```json
{
  "oidc": {
    "microsoft": {
      "clientID": "<client ID you copied from Microsoft>",
      "clientSecret": "<client secret you copied from Microsoft>",
      "displayName": "Microsoft",
      "oidcIssuerURL": "https://login.microsoftonline.com/consumers/v2.0"
    }
  }
}
```

--------------------------------

### Traefik Dynamic Configuration for Authelia and Homechart

Source: https://homechart.app/docs/guides/sso

Defines Traefik's middleware for Authelia's forward authentication and routers for both Authelia and Homechart. Ensure Traefik is configured to use this dynamic configuration file.

```yaml
http:
  middlewares:
    authelia:
      forwardauth:
        address: http://localhost:9091/api/verify?rd=https://auth.example.com:8443
        authResponseHeaders:
          - Remote-Name
          - Remote-Email
        trustForwardHeader: true
  routers:
    authelia:
      service: authelia
      rule: "Host(`auth.example.com`)"
      tls: true
    homechart:
      middlewares:
        - authelia
      service: homechart
      rule: "Host(`homechart.example.com`)"
      tls: true
  services:
    authelia:
      loadBalancer:
        servers:
          - url: http://localhost:9091
    homechart:
      loadBalancer:
        servers:
          - url: http://localhost:3000
```

--------------------------------

### Executing System Commands

Source: https://homechart.app/docs/references/jsonnet

Executes a shell command and returns stdout. Requires enabling via jsonnet_disableGetCmd configuration.

```jsonnet
local getCmd(command, fallback=null) = std.native('getCmd')(command, fallback);

getCmd('ls -al mydir/', 'mydir')
```

--------------------------------

### Generate VAPID keys

Source: https://homechart.app/docs/references/config

Commands to generate the VAPID private key required for Web Push notifications.

```bash
$ ./homechart_linux_amd64 generate-vapid
VEIYXV6qF_enUzycyQYdplDUgi05UM4lPh_FTzYmwX8
```

```bash
$ docker run -it --rm ghcr.io/candiddev/homechart generate-vapid
VEIYXV6qF_enUzycyQYdplDUgi05UM4lPh_FTzYmwX8
```

--------------------------------

### Retrieving Environment Variables

Source: https://homechart.app/docs/references/jsonnet

Fetches the value of an environment variable by key.

```jsonnet
local getEnv(key) = std.native('getEnv')(key);

getEnv('PWD')
```

--------------------------------

### Render Jsonnet String

Source: https://homechart.app/docs/references/jsonnet

Renders a string as Jsonnet code.

```jsonnet
std.native('render')(|||
  local regexMatch(regex, string) = std.native('regexMatch')(regex, string);

  regexMatch('^hello world$', 'hello world')
|||)
```

--------------------------------

### Update Homechart Container

Source: https://homechart.app/docs/guides/get-homechart/self-hosted

Pull the latest Homechart image from the GitHub Container Registry.

```bash
docker pull ghcr.io/candiddev/homechart:latest
```

--------------------------------

### OIDC Provider Configuration

Source: https://homechart.app/docs/guides/sso

Minimal configuration structure for integrating a third-party OIDC provider within the Homechart settings.

```json
{
  "oidc": {
    "google": {
      "clientID": "a-client-id",
      "clientSecret": "a-client-secret",
      "displayName": "Google",
      "oidcIssuerURL": "https://accounts.google.com"
    }
  }
}
```

--------------------------------

### Authelia Configuration

Source: https://homechart.app/docs/guides/sso

Configures Authelia server settings, logging, JWT secret, redirection URL, authentication backend (local file), access control policy, session management, storage, and notifier. This file should be referenced by the Authelia command line.

```yaml
server:
  host: 0.0.0.0
  port: 9091
log:
  level: debug
jwt_secret: C57E160E9CE711D214BF4CCF407DE6C64FCF19A7C20E7C6D7C2FF18826A7E1AA
default_redirection_url: https://auth.example.com:8443
authentication_backend:
  file:
    path: ./users.yaml
    password:
      algorithm: argon2id
      iterations: 1
      salt_length: 16
      parallelism: 8
      memory: 1024 # blocks this much of the RAM. Tune this.
access_control:
  default_policy: one_factor
session:
  name: authelia_session
  domain: example.com
storage:
  encryption_key: superdupersecretsecret
  local:
    path: ./db.sqlite3
notifier:
  filesystem:
    filename: ./notification.txt
```

--------------------------------

### CalDAV Conformance

Source: https://homechart.app/docs/guides/calendar

Details on the specific CalDAV URLs and methods supported by Homechart, noting that it does not support the full WebDAV/CalDAV specification.

```APIDOC
## CalDAV Conformance

### Description
Details on the specific CalDAV URLs and methods supported by Homechart, noting that it does not support the full WebDAV/CalDAV specification.

### Supported URLs and Methods
- `PROPFIND /dav/calendars`
- `PROPFIND /dav/calendars/{calendarID}/`
- `REPORT /dav/calendars/{calendarID}/`
  - Supported Report Sets: `calendar-query`, `calendar-multiget`, `sync-collection`
- `DELETE /dav/calendars/{calendarID}/{itemID}`
- `PUT /dav/calendars/{calendarID}/{itemID}`
- `PROPFIND /dav/principals/`
- `PROPFIND /dav/principals/{principalID}/`
```

--------------------------------

### Add CLI Autocomplete

Source: https://homechart.app/docs/references/cli

Add shell autocompletion for Homechart commands. Source the output in your terminal's shell configuration.

```bash
$ source <(homechart autocomplete)

```

--------------------------------

### Handling Immutable Values

Source: https://homechart.app/docs/references/jsonnet

Shows how to create new objects by extending existing ones or using ternary operators, as Jsonnet values are immutable.

```jsonnet
local object1 = {
  hello: 'world'
}

object1 + {
  hello: 'person'
}
```

```jsonnet
local something = if true then 'else' else 'other';
```