jx/README.md

# jx

# Purpose

These tools work with YAML descriptions of resources (E.g. files, users, containers, etc) for (de)serializing the state of the given resource.  This enables more generically describing the state of a supported resource type, pipeling state transformations and enabling the use of other tools in that process.

# Dependencies

* Go >= 1.21.1

# Releases

**<span style="color:red">v0 releases are unstable and changes may be made to interfaces and specifications.</span>**

Use at your own risk.

# JX Documents

The JX YAML specification is a simple way to describe system resources.  The two main components are `configurations` and `resources`.

## Configurations

```
configurations:
- name: myhttpconfig
  values:
    http_user: jex
    http_password: sample 
- name: myhttptoken
  values:
    authorization_token: abcde123456789
```

## Resources
```
resources:
- type: http
  config: myhttptoken
  transition: read
  attributes:
    endpoint: https://myserver/v1/api
```

# Testing

Testing the current version involves checking out main and building inside of the alpine go build container.

```
git clone https://gitea.rosskeen.house/doublejynx/jx.git

make build-container

make test
```

# Command-line

# Update Resource state

`jx apply decl-runner.yaml`

Create the resources specified in a resource document HTTP endpoint.

`jx apply http://localhost/resources`

Convert a tar archive into resource definitions and apply them (extracts the contents of a tar).

`jx apply https://gitea.rosskeen.house/doublejynx/jx/archive/v0.2.1.tar.gz`

# Read resource state

Read the state of an existing resource (URI) and generate a YAML representation of it.

`jx import -resource file://COPYRIGHT`

## Importing resources from different sources

JX supports importing resources data from various source types, among these are filesystem directories, tar archive contents, containers, iptables chains, installed packages, etc.

Import system packages using the debian package type, and output the resource documents in JSON format.

`jx import --output json:// package://?type=deb`

Import the contents of a tar archive into a resource document.

`jx import ./test.tgz`

Import resource documents from multiple sources.

`jx import repo/packages/build.jx.yaml ./gopkgs.tar.gz`

![Import Doc](md-images/jx-import.gif)

Read a resource document from an http endpoint.

`jx import http://localhost/resources`

# Diff resource documents

![Diff Resources](md-images/jx-diff.gif)

# Examples

Resources:

* [container](examples/container.jx.yaml) [schema](internal/resource/schemas/container.schema.json)
* [container-image](examples/container-image.jx.yaml) [schema](internal/resource/schemas/container-image.schema.json)
* [container-network](examples/container-network.jx.yaml) [schema](internal/resource/schemas/container-network.schema.json)
* [exec](examples/exec.jx.yaml) [schema](internal/resource/schemas/exec.schema.json)
* [file](examples/file.jx.yaml) [schema](internal/resource/schemas/file.schema.json)
* [group](examples/group.jx.yaml) [schema](internal/resource/schemas/group.schema.json)
* [http](examples/http.jx.yaml) [schema](internal/resource/schemas/http.schema.json)
* [iptable](examples/iptable.jx.yaml) [schema](internal/resource/schemas/iptable.schema.json)
* [network_route](examples/network_route.jx.yaml) [schema](internal/resource/schemas/network_route.schema.json)
* [package](examples/package.jx.yaml) [schema](internal/resource/schemas/package.schema.json)
* [user](examples/user.jx.yaml) [schema](internal/resource/schemas/user.schema.json)