### Start Exordos Documentation Server

Source: https://github.com/exordos/exordos_core/blob/master/AGENTS.md

Command to start the local development server for Exordos documentation.

```bash
# Start documentation server
tox -e docs
```

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

### Install Exordos Core CLI Tools

Source: https://github.com/exordos/exordos_core/blob/master/README.md

Installs the Exordos Core CLI tools using a curl command. This is the initial step to start using the platform.

```bash
curl -fsSL https://repo.exordos.com/install.sh | sudo sh
```

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

### Deploy an Element

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Install and run your element on a Exordos Core platform installation. The platform resolves dependencies, installs the element, and starts it.

```bash
exordos elements install <element-name>
```

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

### Service with Shell Dependencies

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Configures a service with pre-start shell commands for setup and post-stop commands for notifications. Ensures environment is ready before the service starts.

```json
{
  "name": "app-with-deps",
  "description": "Application with pre/post commands",
  "path": "/opt/app/start.sh",
  "user": "appuser",
  "target": {
    "kind": "node",
    "node": "12345678-c625-4fee-81d5-f691897b8142"
  },
  "service_type": {
    "kind": "simple",
    "count": 1
  },
  "target_status": "enabled",
  "before": [
    {
      "kind": "shell",
      "command": "mkdir -p /var/log/app && chown appuser:appuser /var/log/app"
    }
  ],
  "after": [
    {
      "kind": "shell",
      "command": "curl -X POST http://monitoring/notify/service-up"
    }
  ]
}
```

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

### Install Qemu for Exordos

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Installs Qemu components required for building Exordos elements. Adds the current user to the kvm group.

```bash
sudo apt update
sudo apt install qemu-kvm mkisofs
sudo adduser $USER kvm
```

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

### Install Exordos Core on Linux

Source: https://github.com/exordos/exordos_core/blob/master/docs/index.md

Use this command to install Exordos Core on a Linux system by downloading and executing the installation script.

```bash
curl -fsSL https://repo.exordos.com/install.sh | sh
```

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

### Define, Build, Start, and Autostart Libvirt Pool

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Configures a new libvirt storage pool named 'default' targeting '/var/lib/libvirt/images/'. It then builds, starts, and enables the pool for autostart on boot.

```bash
sudo virsh pool-define-as default dir --target "/var/lib/libvirt/images/"
sudo virsh pool-build default
sudo virsh pool-start default
sudo virsh pool-autostart default
```

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

### Separate Push Configuration File Example (YAML)

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/push.md

Example of a separate push configuration file (e.g., exordos.push.yaml) defining 'staging' and 'production' repositories.

```yaml
push:
  staging:
    driver: fs
    path: /var/lib/exordos-pools/staging
  production:
    driver: nginx
    url: https://repo.exordos.com/production
```

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

### Exordos Push Configuration Example (YAML)

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/push.md

Example of push configuration in exordos.yaml, defining 'local' and 'remote' repositories with different drivers and paths/URLs.

```yaml
push:
  local:
    driver: fs
    path: /var/lib/exordos-pools/http
  remote:
    driver: nginx
    url: https://repo.exordos.com
```

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

### Example Exordos Manifest

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/manifest.md

This is a complete example of an Exordos manifest file, demonstrating the structure for defining services, compute nodes, and resource imports/exports.

```yaml
name: "core_service_example"
description: "Exordos Core Service Example"
schema_version: 1
version: "1.0.3"
api_version: "v1"

requirements:  # Requirements of the manifest
  core:
    from_version: "0.0.0"
    to_version: "1.0.0"

resources: 
  $core.compute.nodes:
    example_node:
      name: "example-service-node"
      description: "Example service node"
      cores: "$core_service_example.imports.$var_default_cores:value"
      ram: "$core_service_example.imports.$var_default_ram:value"
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      disk_spec:
        kind: "root_disk"
        size: 10
        image: "{{ base_image_url | default('https://repo.exordos.com/exordos-base/0.4.1/exordos-base.raw.gz') }}"
  
  $core.em.services:
    example_service:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      name: "example-service"
      path: "/usr/bin/python3 -m http.server 8080"
      user: "ubuntu"
      group: "ubuntu"
      target:
        kind: "node"
        node: "$core_service_example.compute.nodes.$example_node:uuid"
      service_type:
        kind: "simple"
        count: 1
      target_status: "enabled"

exports:
  my_service:
    link: "$core_service_example.em.services.$example_service"
    kind: "resource"
  my_node:
    link: "$core_service_example.em.services.$example_node"
    
imports:
  var_default_cores:
    element: "$core"
    kind: "resource"
    link: "$core.vs.variables.$default_cores"
  var_default_ram:
    element: "$core"
    kind: "resource"
    link: "$core.vs.variables.$default_ram"

```

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

### Install Exordos Element

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Installs the 'todo-api' element into the Exordos environment, making it available for use.

```bash
exordos elements install todo-api
```

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

### Install Element from Local Manifest File

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/deploy.md

Installs an element using a local manifest file. Provide the path to the YAML manifest file.

```bash
exordos elements install ./manifests/my-element.yaml
```

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

### Run exordos init Command

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/init.md

Basic usage of the exordos init command. Use this to start the interactive wizard for platformizing your project.

```bash
exordos init [OPTIONS]
```

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

### Exordos Elements Install Command Syntax

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/deploy.md

Basic syntax for the 'exordos elements install' command, including placeholder for path or name.

```bash
exordos elements install [OPTIONS] PATH_OR_NAME
```

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

### Manifest Requirements Example

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/manifest.md

Specifies the version constraints for core Exordos elements required by the manifest. Ensure the 'to_version' is compatible with your Exordos installation.

```yaml
core:
  from_version: "0.0.0"
  to_version: "1.0.0"

```

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

### Install Element by Name from Default Repository

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/deploy.md

Installs an element by its name from the default Exordos repository. The command fetches the manifest, resolves dependencies, and provisions the element.

```bash
exordos elements install my-element
```

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

### Install Element from Custom Repository

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/deploy.md

Installs an element from a specified custom repository endpoint. Use the '-r' option followed by the repository URL and the element name.

```bash
exordos elements install -r https://my-repo.example.com/elements/ my-element
```

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

### Install Exordos Element

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/cli.md

This command installs an Exordos element from its repository. It is used after an element has been built or is available in a configured repository.

```bash
exordos elements install <element_name>
```

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

### Install Genesis Core Packages on Ubuntu

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Installs essential packages required for Genesis Core on Ubuntu systems. Ensure you have sudo privileges.

```bash
sudo apt update
sudo apt install qemu-kvm qemu-utils libvirt-daemon-system libvirt-dev mkisofs -y
```

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

### Install Build Dependencies on Linux (Ubuntu)

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Installs necessary packages for building Exordos Core elements on Ubuntu systems. Ensure you have sudo privileges.

```bash
sudo apt update
sudo apt install qemu-kvm mkisofs
```

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

### Bootstrap Genesis Core Locally

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Use the devtools bootstrap command to start Genesis Core locally. Ensure you have the genesis-core.raw image available.

```bash
genesis bootstrap -i genesis-core.raw -m core
```

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

### Example Output Artifacts Structure

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

After a successful build, artifacts including inventory, VM disk images, and compiled manifests are created in the specified output directory.

```text
output/
├── inventory.json          # Build manifest listing all produced artifacts
├── images/                 # Built VM disk images
│   └── <element-name>.<format>
└── manifests/              # Compiled manifests for each element
    └── <element-name>.yaml
```

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

### Nested Resource Reference Example

Source: https://github.com/exordos/exordos_core/wiki/NewRefProposal

Demonstrates how to reference nested resources within the new proposal.

```yaml
$core.compute.sets.$xxx.nodes.$yyy.ports:
    main_port:
      ipv4: "127.0.0.1"
      ipv6: "::1"
```

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

### Collection Reference Example

Source: https://github.com/exordos/exordos_core/wiki/NewRefProposal

Illustrates referencing a collection of compute sets.

```yaml
$core.compute.sets:
    controller:
      replicas: 3
      cores: 1
      ram: 1024
      image: "$core.object.artifacts[]"
      node_type: "VM"
```

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

### Exordos Commit Message Example

Source: https://github.com/exordos/exordos_core/blob/master/AGENTS.md

An example of a well-formatted commit message following the specified conventions.

```text
feat(repo): add HTTP server proxy driver

- Implement SimplePythonRepoDriver for file serving
- Add port configuration and error handling
- Include unit tests for driver lifecycle

Closes #123
```

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

### Prepare Remote System for Nginx and Socat

Source: https://github.com/exordos/exordos_core/blob/master/docs/network/load_balancer.md

Installs necessary packages (nginx-full, socat) and configures the system to allow binding to privileged ports for remote traffic forwarding.

```console
# We may use nginx with proxy_protocol and socat for udp
apt install nginx-full socat

# Apply binding to privileged ports
echo 'net.ipv4.ip_unprivileged_port_start=0' > /etc/sysctl.d/50-unprivileged-ports.conf
sysctl --system
```

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

### Basic HTTPS Load Balancer Configuration

Source: https://github.com/exordos/exordos_core/blob/master/docs/network/load_balancer.md

This snippet demonstrates a basic HTTPS load balancer setup. It includes defining the load balancer, backend pools, vhosts for HTTP and HTTPS, routes for both, and a DNS A record. Ensure certificates are correctly referenced.

```yaml
...
requirements:
  core:
    from_version: "0.0.0"

imports:
  core_public_domain:
    element: "$core"
    kind: "resource"
    link: "$core.dns.domains.$public_domain"

  $core.network.lb:
    basic_lb:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      type:
        kind: core
        ram: 1024
        cpu: 2
  $core.network.lb.$basic_lb.backend_pools:
    basic_backend_http:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      parent: $core.network.lb.$basic_lb:uuid
      endpoints:
        - kind: host
          host: $core.compute.nodes.$exordos_basic:default_network:ipv4
          port: 80
  $core.network.lb.$basic_lb.vhosts:
    basic_http:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      parent: $core.network.lb.$basic_lb:uuid
      domains:
        - f"example.{$basic.imports.$core_public_domain:name}"
        - f"www.example.{$basic.imports.$core_public_domain:name}"
      protocol: http
      port: 80
    basic_https:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      parent: $core.network.lb.$basic_lb:uuid
      domains:
        - f"example.{$basic.imports.$core_public_domain:name}"
        - f"www.example.{$basic.imports.$core_public_domain:name}"
      protocol: https
      port: 443
      cert:
        kind: raw
        crt: $core.secret.certificates.basic_cert:cert
        key: $core.secret.certificates.basic_cert:key
  $core.network.lb.$basic_lb.vhosts.$basic_http.routes:
    basic_http_route:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      parent: $core.network.lb.$basic_lb.vhosts.$basic_http:uuid
      condition:
        kind: prefix
        value: "/"
        actions:
          - kind: redirect
            url: f"https://example.{$basic.imports.$core_public_domain:name}"
  $core.network.lb.$basic_lb.vhosts.$basic_https.routes:
    basic_https_route:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      parent: $core.network.lb.$basic_lb.vhosts.$basic_https:uuid
      condition:
        kind: prefix
        value: "/"
        actions:
          - kind: backend
            pool: $core.network.lb.$basic_lb.backend_pools.$basic_backend_https:uuid
  $basic.imports.$core_public_domain.records:
    basic_a_record:
      domain: "$basic.imports.$core_public_domain:uuid"
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      type: "A"
      record:
        kind: "A"
        name: "example"
        address: "$core.network.lb.$basic_lb:index(ipsv4, 0)"
  $core.secret.certificates:
    basic_cert:
      name: basic_cert
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      email: user@exordos.com
      domains:
        f"example.{$basic.imports.$core_public_domain:name}"
        f"*.example.{$basic.imports.$core_public_domain:name}"
```

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

### Manifest Exports Example

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/manifest.md

Defines resources that are made available by this manifest. The 'link' property points to the actual resource defined within the manifest.

```yaml
my_service:
  link: "$core_service_example.em.services.$example_service"
  kind: "resource" # kind of the export, now only `resource` is supported, may be omitted

```

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

### Manifest Imports Example

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/manifest.md

Declares external resources or variables needed by the manifest. The 'link' specifies the exact path to the imported element.

```yaml
var_default_cores:
  element: "$core"  # element, from that the import is made
  kind: "resource" # kind of the import, now only `resource` is supported, may be omitted
  link: "$core.vs.variables.$default_cores"   # link to the resource (element, that the import is made, maybe be another)

```

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

### Endpoint with Permission Guard

Source: https://github.com/exordos/exordos_core/blob/master/docs/iam/permissions_overview.md

An example of an endpoint that uses the `require_permission` decorator to protect the `create_vm` action. This ensures only users with the 'compute.vm.create' permission can invoke this endpoint.

```python
@require_permission("compute.vm.create")
def create_vm(request):
    payload = request.json
    # VM creation business logic
    return {"status": "ok"}, 201
```

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

### Build with Custom Manifest Variables

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Passes additional variables to manifest templates during the build process. This example injects the short commit hash.

```bash
exordos build --manifest-var commit_hash=$(git rev-parse --short HEAD) .
```

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

### Add Hypervisor to Genesis Core

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Register a hypervisor with Genesis Core using a POST request to the /v1/hypervisors/ endpoint. Include the authorization token and detailed driver specifications. Choose the appropriate storage_pool and connection_uri based on your setup (ZFS/qcow, TCP/SSH).

```json
{
    "driver_spec": {
        "driver": "libvirt",
        "iface_mtu": 1500,
        "network_type": "network",
        "network": "genesis-core-net",
        "storage_pool": "default", // for qcow
        "storage_pool": "rpool", // for ZFS
        "connection_uri": "qemu+tcp://10.20.0.1/system", // for TCP connect
        "connection_uri": "qemu+ssh://ubuntu@10.20.0.1:22/system?no_verify=1", // for SSH connect
        "machine_prefix": "dev-"
    },
    "avail_cores": 4,
    "avail_ram": 4096,
    "all_cores": 4,
    "all_ram": 4096,
    "status": "ACTIVE"
}
```

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

### Get Information on Libvirt Default Pool

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Retrieves and displays detailed information about the libvirt 'default' storage pool. This command helps verify the pool's status and configuration.

```bash
sudo virsh pool-info default
```

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

### Get Admin Token for Genesis Core

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Obtain an admin access token by sending a POST request to the /v1/iam/clients/{client_id}/actions/get_token/invoke endpoint. Replace placeholders with your actual username and password.

```bash
curl --location 'http://10.20.0.2:11010/v1/iam/clients/00000000-0000-0000-0000-000000000000/actions/get_token/invoke' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'username=<YOUR_ADMIN_USERNAME>' \
    --data-urlencode 'password=<YOUR_ADMIN_PASSWORD>' \
    --data-urlencode 'client_id=GenesisCoreClientId' \
    --data-urlencode 'client_secret=GenesisCoreClientSecret' \
    --data-urlencode 'scope=' \
    --data-urlencode 'ttl=86400'
```

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

### Initialize an Element

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Use this command to set up an existing project as a Exordos Core element. It launches an interactive wizard to generate necessary configuration files.

```bash
exordos init
```

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

### Bootstrap Exordos Platform (Remote Repository)

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Deploys the Exordos platform using a prebuilt image fetched from the official remote repository. This is the default method if no local image is specified.

```bash
exordos bootstrap -i https://repo.exordos.com/exordos-elements/core/0.0.6/ -m core
```

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

### Initialize Local Host as Hypervisor

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Initializes the current machine as a hypervisor for the Exordos platform. This command configures libvirt for managing virtual machines.

```bash
exordos compute hypervisors init
```

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

### Bootstrap Exordos Platform (Local Build)

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Deploys the Exordos platform from a locally built raw image file. This is useful for development or testing custom builds.

```bash
exordos bootstrap -i /path/to/exordos-core.raw -m core
```

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

### Get a Permission

Source: https://github.com/exordos/exordos_core/wiki/IAM-(Identity-and-Access-Management)-Documentation

Retrieves a specific permission by its unique identifier.

```APIDOC
## GET /v1/iam/permissions/{permission_uuid}

### Description
Retrieves a specific permission using its UUID.

### Method
GET

### Endpoint
/v1/iam/permissions/{permission_uuid}

### Parameters
#### Path Parameters
- **permission_uuid** (string) - Required - The unique identifier of the permission to retrieve.

### Response
#### Success Response (200 OK)
- **uuid** (string) - The unique identifier for the permission.
- **name** (string) - The name of the permission.
- **description** (string) - The description of the permission.
- **created_at** (string) - The timestamp when the permission was created.
- **updated_at** (string) - The timestamp when the permission was last updated.
- **status** (string) - The status of the permission (e.g., `ACTIVE`).

#### Response Example
```json
{
  "uuid": "5a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "name": "compute.vm.create",
  "description": "Permission to create a virtual machine",
  "created_at": "2025-08-21T07:38:04.778680Z",
  "updated_at": "2025-08-21T07:38:04.778688Z",
  "status": "ACTIVE"
}
```
```

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

### Get User Roles

Source: https://github.com/exordos/exordos_core/wiki/IAM-(Identity-and-Access-Management)-Documentation

Retrieves all roles assigned to a specific user.

```APIDOC
## GET /v1/iam/users/{user_uuid}/actions/get_my_roles

### Description
Retrieves all roles assigned to a specific user.

### Method
GET

### Endpoint
/v1/iam/users/{user_uuid}/actions/get_my_roles

### Parameters
#### Path Parameters
- **user_uuid** (string) - Required - The UUID of the user whose roles are to be retrieved.

### Response
#### Success Response (200)
- **roles** (array) - A list of roles assigned to the user.
  - Each role object may contain details like role name, UUID, etc. (details not specified in source)

### Response Example
(Response structure not fully detailed in source, but would typically be a list of role objects)
```json
{
  "roles": [
    {
      "uuid": "6b2c3d4e-5f67-789a-bcde-f01234567890",
      "name": "BillingOperator"
    }
  ]
}
```
```

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

### Bootstrap Exordos Platform (Versioned)

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Deploys the Exordos platform using a specified version. Replace <version> with the desired platform version. The -f flag forces a rebuild if the output already exists.

```bash
exordos bootstrap -i <version> -f -m core --ssh-public-key /path/to/public/key
```

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

### Get service details

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Retrieves the details of a specific service using its UUID.

```APIDOC
## GET /v1/em/services/<uuid>

### Description
Gets service details.

### Method
GET

### Endpoint
/v1/em/services/<uuid>

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the service.
```

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

### Basic Exordos Build Command

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Initiates a standard build process for Exordos elements from the project directory. This command resolves dependencies and provisions the element.

```bash
exordos build .
```

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

### Service with Service Dependency

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Defines a service that depends on another service to be running before it starts. Ensures prerequisite services are available.

```json
{
  "name": "dependent-service",
  "description": "Service that depends on another service",
  "path": "/opt/app/dependent-start.sh",
  "user": "appuser",
  "target": {
    "kind": "node",
    "node": "12345678-c625-4fee-81d5-f691897b8142"
  },
  "service_type": {
    "kind": "simple",
    "count": 1
  },
  "target_status": "enabled",
  "before": [
    {
      "kind": "service",
      "service": "abcdef12-3456-7890-abcd-ef1234567890",
      "service_name": "base-service"
    }
  ],
  "after": []
}
```

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

### Define VM Image Build Configuration in exordos.yaml

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Configure VM image builds by defining elements in `exordos.yaml`. Specify image names, formats, base profiles, provisioning scripts, and environment variables.

```yaml
elements:
  - manifest: manifests/core.yaml.j2
    images:
      - name: my-app
        format: qcow2
        profile: exordos_base
        script: install.sh
        envs:
          - APP_PORT=8080
          - LOG_LEVEL=info
          - DATABASE_URL
```

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

### Get IAM Permission by ID

Source: https://github.com/exordos/exordos_core/wiki/IAM-(Identity-and-Access-Management)-Documentation

Retrieve a specific IAM permission using its unique identifier. This is useful for verifying permission details.

```http
GET /v1/iam/permissions/5a1b2c3d-4e5f-6789-abcd-ef0123456789
Authorization: Bearer <token>
```

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

### Bootstrap Exordos Deployment

Source: https://github.com/exordos/exordos_core/blob/master/AGENTS.md

Command to initiate the bootstrap process for deploying Exordos.

```bash
# Bootstrap deployment
make bootstrap
```

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

### Clone ToDo Application Project

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Clones the sample ToDo application repository and navigates into the project directory.

```bash
git clone https://github.com/infraguys/todo_application.git && cd todo_application
```

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

### Get User Roles

Source: https://github.com/exordos/exordos_core/wiki/IAM-(Identity-and-Access-Management)-Documentation

Retrieve all roles assigned to a specific user. This is useful for auditing or understanding a user's current access level.

```http
GET /v1/iam/users/7c3d4e5f-6789-89ab-cdef-123456789012/actions/get_my_roles
Authorization: Bearer <token>
```

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

### Basic Exordos Push

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/push.md

Execute a basic push from your project directory after a successful build. This command reads exordos.yaml, finds the push configuration, and uploads element artifacts from the output/ directory to configured repositories.

```bash
exordos push
```

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

### Exordos Build Command Syntax

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Basic syntax for running the exordos build command. Specify the project directory to initiate the build process.

```bash
exordos build [OPTIONS] PROJECT_DIR
```

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

### Configure Hypervisor with Token

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Send a POST request to the Genesis Core API to add a hypervisor. Ensure you replace 'XXXX' with the admin token obtained earlier. The request body specifies hypervisor details like cores, RAM, and connection URIs.

```bash
curl --location --globoff 'http://10.20.0.2:11010/v1/hypervisors/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXX' \
--data '{ ... }'
```

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

### Push to Specific Target Repository

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/push.md

If your exordos.yaml defines multiple repositories, use the --target option to specify which one to push to. For example, to push to a repository named 'local'.

```bash
exordos push --target local
```

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

### Initialize Exordos Project with Flags

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Initializes a new Exordos element for a Python FastAPI project using command-line flags for configuration. This includes specifying project details, package manager, database, and repository information.

```bash
exordos init \
  --project-name todo_application \
  --project-type python \
  --project-systemd-services "todo-api" \
  --project-url "https://github.com/infraguys/todo_application" \
  --project-python-package-manager "pip" \
  --enable-pgsql \
  --author-name "Developer" \
  --author-email "dev@example.com" \
  --manifest-description "A simple ToDo list element" \
  --repository "https://repo.exordos.com/exordos-elements" \
  --pgsql-usage-mode "own_cluster" \
  --pgsql-database-name "todo_api" \
  --pgsql-username "todo_api" \
  --ci-cd "none"
```

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

### Build Exordos Element

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/cli.md

Use this command to build all necessary artifacts for an Exordos element from its repository. This includes images, manifests, and other required components. Ensure you are in the project directory before running.

```bash
exordos build <element_name>
```

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

### List All Libvirt Storage Pools

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Displays all available libvirt storage pools, including inactive ones. Useful for checking existing configurations before creating new pools.

```bash
sudo virsh pool-list --all
```

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

### List Exordos Compute Hypervisors

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Lists all configured compute hypervisors within the Exordos platform. This command requires the Exordos CLI to be configured with a valid context.

```bash
exordos compute hypervisors list
```

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

### Build Exordos Core Image

Source: https://github.com/exordos/exordos_core/blob/master/AGENTS.md

Command to build the core Docker image for Exordos.

```bash
# Build core image
make build_core
```

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

### Manifest with New Reference Proposal

Source: https://github.com/exordos/exordos_core/wiki/NewRefProposal

This snippet shows a complete manifest using the new reference proposal for resources like artifacts, compute sets, and configurations.

```yaml
Name: foo_element
SchemaVersion: 1
Version: "0.0.1"

Requires:
  core: [">= 0.0.0", "< 1.0.0"]

Resources:
  $core.object.artifacts:
    controller:
      source: "https://github.com/orgs/infraguys/images/controller.img"
    template:
      source: "https://github.com/orgs/infraguys/templates/template.j2"

  $core.compute.sets:
    controller:
      replicas: 3
      cores: 1
      ram: 1024
      image: "$core.object.artifacts.$controller.image_uuid"
      node_type: "VM"

  $core.config.configs:
    controller_conf:
      path: "/etc/controller/controller.env"
      target:
        kind: "set"
        node: "$core.compute.sets.$controller.uuid"
      body:
        kind: "collection_template"
        template: "$core.object.artifacts.$template.location"
        params:
          node_ip: "$core.compute.sets.$controller.nodes[].ipv4"
      on_change:
        kind: "command"
        command: "systemctl restart controller.service"
```

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

### Create Basic Node Set

Source: https://github.com/exordos/exordos_core/wiki/NodeSets

Use this curl command to create a new Node Set with specified properties. The 'replicas' field determines the number of nodes to be launched.

```bash
curl --location 'http://10.20.0.2:11010/v1/sets/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{ \
    "uuid": "00000000-0000-0000-0000-000000000001", \
    "name": "set", \
    "project_id": "00000000-0000-0000-0000-000000000000", \
    "root_disk_size": 10, \
    "cores": 1, \
    "ram": 1024, \
    "replicas": 3, \
    "image": "http://10.20.0.1:8080/genesis-base.raw" \
}'
```

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

### Build an Element

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/index.md

Compile and package your element along with its artifacts using the build configuration in `exordos.yaml`. The output is stored locally and tagged with the element version.

```bash
exordos build
```

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

### Create a Role

Source: https://github.com/exordos/exordos_core/wiki/IAM-(Identity-and-Access-Management)-Documentation

Use this endpoint to create a new role with a name and description. Ensure you have a valid authentication token.

```http
POST /v1/iam/roles/
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "BillingOperator",
  "description": "Billing operator with rights to manage accounts"
}
```

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

### Exordos Push with Separate Configuration File

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/push.md

Specify a separate configuration file for push settings using the -c or --exordos-cfg-file option. This allows for different push configurations without modifying the main exordos.yaml.

```bash
exordos push -c exordos.push.yaml
```

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

### Create Virtual Host Configuration

Source: https://github.com/exordos/exordos_core/blob/master/docs/network/load_balancer.md

Defines a virtual host for serving web content over HTTP, specifying domains and ports.

```json
{
  "name": "web-vhost",
  "description": "Web server vhost",
  "protocol": "http",
  "port": 80,
  "domains": ["example.com", "www.example.com"],
}
```

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

### Initialize Swagger UI with OpenAPI Spec

Source: https://github.com/exordos/exordos_core/blob/master/docs/openapi/openapi_status.md

This script initializes Swagger UI to display the OpenAPI specification. It fetches the YAML spec, parses it, and then renders the UI in the specified DOM element. Ensure the path to 'openapi_status.yaml' is correct.

```javascript
fetch('../openapi_status.yaml')
  .then(response => response.text())
  .then(yamlText => {
    const spec = jsyaml.load(yamlText);
    SwaggerUIBundle({
      spec: spec,
      dom_id: '#swagger-ui',
      presets: [SwaggerUIBundle.presets.apis],
      validatorUrl: null,
      tryItOutEnabled: true
    });
  })
  .catch(err => {
    console.error('Failed to load spec:', err);
    document.getElementById('swagger-ui').innerHTML = '<p>Error loading API spec: ' + err.message + '</p>';
  });
```

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

### Configure ZFS Storage Pool for Libvirt

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Set up a ZFS storage pool for zvols and define it within libvirt. This ensures efficient storage management for virtual machine disks.

```bash
zpool create rpool ... # create pool itself
zfs create -o volmode=dev rpool/disks
virsh pool-define-as --name rpool --source-name rpool/disks --type zfs
virsh pool-start rpool
virsh pool-autostart rpool
```

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

### Issue a Certificate with Wildcard and Multiple Domains

Source: https://github.com/exordos/exordos_core/blob/master/docs/secret/certificates.md

This snippet demonstrates how to issue a certificate that supports wildcard domains and multiple specific domains. It's useful for managing certificates for subdomains and the main domain simultaneously.

```bash
curl --location 'http://10.20.0.2:11010/v1/secret/certificates/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MY_TOKEN' \
--data-raw '{
    "name": "my-cert",
    "project_id": "00000000-0000-0000-0000-000000000000",
    "method": {
        "kind": "dns_core"
    },
    "constructor": {
        "kind": "plain"
    },
    "email": "user@exordos.com",
    "domains": ["*.test1.cdns.exordos.com", "test1.cdns.exordos.com"]
}'
```

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

### Build Only Images

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Configures the build process to generate only VM disk images, skipping the creation of manifests and other artifacts.

```bash
exordos build --only-images
```

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

### Issue a Certificate with Wildcard Domains using dns_core

Source: https://github.com/exordos/exordos_core/wiki/Certificates

This `curl` command demonstrates issuing a certificate that includes wildcard domains. It is similar to the basic certificate issuance but allows for `*.example.com` patterns in the `domains` list.

```bash
curl --location 'http://10.20.0.2:11010/v1/secret/certificates/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MY_TOKEN' \
--data-raw '{
    "name": "my-cert",
    "project_id": "00000000-0000-0000-0000-000000000000",
    "method": {
        "kind": "dns_core"
    },
    "constructor": {
        "kind": "plain"
    },
    "email": "user@genesis-core.tech",
    "domains": ["*.test1.cdns.genesis-core.tech", "test1.cdns.genesis-core.tech"]
}'
```

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

### Configure Exordos CLI Context

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Creates a named context 'admin' with the provided admin username and password, setting it as the active context for the Exordos CLI. This allows managing the platform using CLI commands.

```bash
exordos settings set-context local --name admin -u <ADMIN_USERNAME> -p <ADMIN_PASSWORD> --current
```

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

### Create a Role Binding

Source: https://github.com/exordos/exordos_core/wiki/IAM-(Identity-and-Access-Management)-Documentation

Assign a role to a user for a specific project. This links a user to a role, granting them the permissions associated with that role within the project context.

```http
POST /v1/iam/role_bindings/
Content-Type: application/json
Authorization: Bearer <token>

{
  "user": "7c3d4e5f-6789-89ab-cdef-123456789012",
  "role": "6b2c3d4e-5f67-789a-bcde-f01234567890",
  "project": "8d4e5f67-789a-9abc-def1-234567890123"
}
```

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

### Create Load Balancer Configuration

Source: https://github.com/exordos/exordos_core/blob/master/docs/network/load_balancer.md

Defines the basic configuration for a load balancer, including its name, description, and type with resource specifications.

```json
{
  "name": "my-load-balancer",
  "description": "Production load balancer",
  "type": {
    "kind": "core",
    "cpu": 2,
    "ram": 1024,
    "disk_size": 20,
    "nodes_number": 2
  }
}
```

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

### Exordos Push Command Syntax

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/push.md

The basic syntax for the exordos push command. Use PROJECT_DIR to specify the project directory if not in the current directory.

```bash
exordos push [OPTIONS] [PROJECT_DIR]
```

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

### Issue a Certificate with dns_core

Source: https://github.com/exordos/exordos_core/wiki/Certificates

Use this `curl` command to issue a new certificate. Specify the certificate name, project ID, issuance method (`dns_core`), constructor (`plain`), email, and the domains for which the certificate is intended.

```bash
curl --location 'http://10.20.0.2:11010/v1/secret/certificates/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MY_TOKEN' \
--data-raw '{
    "name": "my-cert",
    "project_id": "00000000-0000-0000-0000-000000000000",
    "method": {
        "kind": "dns_core"
    },
    "constructor": {
        "kind": "plain"
    },
    "email": "user@genesis-core.tech",
    "domains": ["test0.cdns.genesis-core.tech"]
}'
```

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

### Include Swagger UI and JS-YAML Libraries

Source: https://github.com/exordos/exordos_core/blob/master/docs/openapi/openapi_status.md

These script tags include the necessary libraries for Swagger UI and JS-YAML. Ensure these are loaded before the initialization script.

```html
<script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
<script src="https://unpkg.com/js-yaml@4/dist/js-yaml.min.js"></script>
```

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

### Define Contexts with Core.contexts and template_context

Source: https://github.com/exordos/exordos_core/wiki/Proposals

Use `Core.contexts` to define data structures and `template_context` for configurations that work with these contexts. This allows for convenient data formatting and template rendering.

```yaml
Name: FooElement
SchemaVersion: 1
Version: "0.0.1"

Requires:
  Core: [" B= 0.0.0", "< 1.0.0"]

Resources:
  Core.artifacts:
    controller:
      source: "https://github.com/orgs/infraguys/images/controller.img"
    template:
      source: "https://github.com/orgs/infraguys/templates/template.j2"

  Core.sets:
    controller:
      replicas: 3
      cores: 1
      ram: 1024
      image: "{{RESOURCE.Core.artifacts.controller.image_uuid}}"
      node_type: "VM"

  # NOTE(akremenetsky): In my opinion it's very closes to `Values` functionality
  Core.contexts:
    # Use a special context to form data in convient format.
    controller:
      # `set_getter`. A context to get data from a set and prepare it for the configuration.
      # The context will form matching among nodes and its ip addresses and hostnames.
      kind: "set_getter"
      set: "{{RESOURCE.Core.sets.controller.uuid}}"
      attributes:
        - hostname
        - ipv4
    controller_data_fetcher:
      kind: "http"
      cmd: "https://github.com/orgs/infraguys/data/binary"

  Core.configs:
    controller_conf:
      path: "/etc/controller/controller.env"
      target:
        # Work with sets
        kind: "set"
        set: "{{LOCAL.Core.sets.controller.uuid}}"
      body:
        # Special kind to work with sets and contexts  
        kind: "template_context"

        # The same template as for the node case.
        template: "{{RESOURCE.Core.artifacts.template.location}}"

        params:
          # Reference to the context. The `template_context` know how to
          # match IP addresses from the context with the template
          node_ip: "{{RESOURCE.Core.contexts.controller.ipv4}}"
      on_change:
        kind: "command"
        command: "systemctl restart controller.service"

```

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

### Basic Service Manifest

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Defines a simple service to be deployed on a single compute node. Ensure the 'my_service' name and project ID are correctly set.

```yaml
requirements:
  core:
    from_version: "0.0.0"

imports:
  core_compute_node:
    element: "$core"
    kind: "resource"
    link: "$core.compute.nodes.$my_node"

resources:
  $core.em.services:
    my_service:
      project_id: "12345678-c625-4fee-81d5-f691897b8142"
      name: "my-app-service"
      path: "/opt/myapp/start.sh"
      user: "appuser"
      group: "appuser"
      target:
        kind: "node"
        node: "$core.compute.nodes.$my_node:uuid"
      service_type:
        kind: "simple"
        count: 1
      target_status: "enabled"
      before:
        - kind: "shell"
          command: "mkdir -p /var/log/myapp"
      after: []

```

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

### Add User to Libvirt and KVM Groups

Source: https://github.com/exordos/exordos_core/wiki/BasicUsage

Adds the current user to the 'libvirt' and 'kvm' groups to grant necessary permissions for managing virtual machines. This change may require logging out and back in.

```bash
sudo adduser $USER libvirt
sudo adduser $USER kvm
```

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

### Run All Exordos Core Tests

Source: https://github.com/exordos/exordos_core/blob/master/AGENTS.md

Command to execute all unit and functional tests across multiple Python versions using tox.

```bash
# Run all tests (unit + functional)
tox -e py310,py311,py312,py313,py314
```

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

### Create a Permission

Source: https://github.com/exordos/exordos_core/blob/master/docs/iam/permissions_overview.md

Use this endpoint to create a new permission. Ensure the Authorization header is set with a valid token.

```http
POST /v1/iam/permissions/
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "compute.vm.create",
  "description": "Permission to create a virtual machine"
}
```

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

### Simple Service Configuration

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Defines a standard service that runs on a specific node. Use for typical application services.

```json
{
  "name": "my-web-server",
  "description": "Production web server",
  "path": "/usr/local/bin/start-web-server.sh",
  "user": "www-data",
  "group": "www-data",
  "target": {
    "kind": "node",
    "node": "12345678-c625-4fee-81d5-f691897b8142"
  },
  "service_type": {
    "kind": "simple",
    "count": 2
  },
  "target_status": "enabled",
  "before": [],
  "after": []
}
```

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

### Include Optional Dependencies

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Marks a dependency as optional, allowing the build to continue even if the source is unavailable. This is useful for development-only resources.

```yaml
deps:
  - dst: /opt/gcl_sdk
    optional: true
    path:
      env: LOCAL_GENESIS_SDK_PATH
```

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

### Configure Exordos CLI Realm

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Registers the Exordos platform endpoint with the name 'local' and sets it as the active realm for the Exordos CLI. This command should be run after successful platform bootstrap.

```bash
exordos settings set-realm local --endpoint http://10.20.0.2:11010 --current
```

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

### Run Exordos Core Linters

Source: https://github.com/exordos/exordos_core/blob/master/AGENTS.md

Commands to check code style and perform type checking using tox.

```bash
# Run linters
tox -e ruff-check    # Check code style
tox -e mypy          # Type checking
```

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

### Use Environment Variables in Provisioning Script

Source: https://github.com/exordos/exordos_core/blob/master/docs/app-developer-guide/build.md

Access environment variables passed from `exordos.yaml` within your VM provisioning scripts to dynamically configure applications.

```bash
#!/bin/bash
# install.sh

echo "Starting application on port $APP_PORT"
echo "Log level set to: $LOG_LEVEL"

# DATABASE_URL will be passed if set in the environment
if [ -n "$DATABASE_URL" ]; then
    echo "Database configured: $DATABASE_URL"
fi
```

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

### List all services

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Retrieves a list of all available services.

```APIDOC
## GET /v1/em/services/

### Description
Lists all services.

### Method
GET

### Endpoint
/v1/em/services/
```

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

### Create a new service

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/service.md

Creates a new service.

```APIDOC
## POST /v1/em/services/

### Description
Creates a new service.

### Method
POST

### Endpoint
/v1/em/services/
```

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

### List Exordos Elements

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Lists all deployed elements within the Exordos platform. This command is used to view the components and services running on the platform.

```bash
exordos elements list
```

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

### Import API

Source: https://github.com/exordos/exordos_core/blob/master/docs/em/api_documentation.md

Endpoints for importing Element resources.

```APIDOC
## GET /v1/em/elements/{ElementUuid}/imports/

### Description
Retrieves a list of imports for a specific element.

### Method
GET

### Endpoint
/v1/em/elements/{ElementUuid}/imports/

### Parameters
#### Path Parameters
- **ElementUuid** (string) - Required - The UUID of the element.
```

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

### Load and Display OpenAPI Spec with Swagger UI

Source: https://github.com/exordos/exordos_core/blob/master/docs/openapi/openapi_boot.md

This script loads the OpenAPI specification from a YAML file, parses it using js-yaml, and then initializes Swagger UI to display the interactive API documentation. It includes basic error handling for the fetch operation.

```javascript
fetch('../openapi_boot.yaml')
  .then(response => response.text())
  .then(yamlText => {
    const spec = jsyaml.load(yamlText);
    SwaggerUIBundle({
      spec: spec,
      dom_id: '#swagger-ui',
      presets: [SwaggerUIBundle.presets.apis],
      validatorUrl: null,
      tryItOutEnabled: true
    });
  })
  .catch(err => {
    console.error('Failed to load spec:', err);
    document.getElementById('swagger-ui').innerHTML = '<p>Error loading API spec: ' + err.message + '</p>';
  });
```

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

### SSH Access to Core VM

Source: https://github.com/exordos/exordos_core/blob/master/docs/usage/local_deployment.md

Connects to the core Exordos virtual machine via SSH. Assumes a public SSH key was provided during bootstrap and uses the default IP address for the core VM.

```bash
ssh ubuntu@10.20.0.2
```