Get started#

Requirements#

Docker Engine and Docker Compose (v2.15.1 or higher)
python3, pip, zip
Access to https://downloads.eclecticiq.com/extensions-sdk-packages

Run the EDK-ERE#

Download the docker-setup-alpha3.tar.gz file.

wget https://downloads.eclecticiq.com/extensions-sdk-packages/alpha3/docker-setup-alpha3.tar.gz  --username <username>@<domain> --ask-password

Extract the docker-setup-alpha3.tar.gz file.
```
tar -xzf docker-setup-alpha3.tar.gz
```

Setup the SSL certificates#

Run the cert_config_generator.sh script.
```
./cert_config_generator.sh
```

Start the EKE-ERE#

Rename the example.env file to .env.

Do not commit .env to version control.
Inside .env, change the value for the variables listed below to more secure values:
- EIQ_EDK_REDIS_ADMIN_PASSWORD
- EIQ_EDK_POSTGRES_ADMIN_PASSWORD
- EIQ_EDK_POSTGREST_AUTH_PASSWORD
- EIQ_EDK_MANAGEMENT_DB_JWT_SECRET_KEY
- EIQ_EDK_SHARED_DB_JWT_SECRET_KEY
- EIQ_EDK_SECRETARY_JWT_SECRET_KEY
- EIQ_EDK_MANAGEMENT_APP_JWT_SECRET_KEY
- EIQ_EDK_ENV_SUPERVISORD_PASSWORD

Run Docker Compose.

docker compose --env-file .env -f docker-compose.yml up

Stop Docker Compose using Ctrl + C.

Note

Alternatively, add the -d flag to run Docker Compose in the background. In that case, run docker compose --env-file .env -f docker-compose.yml down to stop the EDK-ERE.

Initialize your project#

If not present on your system, install cookiecutter.
```
pip install cookiecutter
```

Create directory for your extension.

mkdir -p <PATH-TO-EXTENSION-DIR> && cd <PATH-TO-EXTENSION-DIR>

Create your project.

cookiecutter https://github.com/eclecticiq/extensions-store.git --directory extension-template

Fill in the inputs requested by CookieCutter.

Package your extension#

Requirements#

tar
gzip
gpg

Create GPG key to sign package#

You need to sign your package with a GPG key. Use a pre-existing GPG key, or create one:

Create a GPG key.
```
gpg --full-generate-key
```
Get your key ID.
```
gpg -k
```
Store it in KEY_ID.
```
KEY_ID=<my-key-id>
```

Export public key.

gpg --output pubkey.gpg --export ${KEY_ID}

Package extension#

Export the setenv.sh script.
```
source setenv.sh
```

Run packaging script.

./create_package.sh --source /path-to-src/ -k ${KEY_ID}

Verify signature.

gpg --verify ./${PACKAGE_NAME}_${VERSION}*.tar.gz.gpg

If your package has a valid signature, gpg displays a Good signature:

gpg: Signature made Fri Oct 28 15:19:32 2022 CEST
gpg:                using RSA key {KEY_ID}
gpg: Good signature from {KEY_INFORMATION}

Your newly created files are stored in your extension directory.

Using your package and your public key, you are now ready to install your extension on the EDK-ERE.

Install extension on the EDK-ERE#

Install the required modules.

pip install pyjwt datetime python-dotenv pathlib

Save the script below in generate-jwt.py.

#!/usr/bin/env python3
from jwt import encode
from datetime import datetime
from os import environ
from dotenv import load_dotenv
from pathlib import Path


load_dotenv(dotenv_path=Path('.env'))
payload = {
'sub': environ.get('EIQ_EDK_VALID_AUTH_TOKEN_SUBJECT'),
'iat': datetime.utcnow(),
'role': environ.get('EIQ_EDK_MANAGEMENT_APP_ROLE'),
}
this_secret = environ.get('EIQ_EDK_MANAGEMENT_APP_JWT_SECRET_KEY')

try:
    my_token = encode(
    payload=payload,
    key=this_secret,
    algorithm='HS256',
    )
    print(my_token)
except TypeError:
    print('.env was not found. JWT cannot be generated.')

Run the script to generate your JWT.
```
python3 generate-jwt.py
```
Note

The script must be run on the same location as .env.

Import your public GPG key.

curl --location --request POST 'https://localhost:5001/gpg-keys' \
--header 'Authorization: Bearer <YOUR_JWT>' \
--cacert cert/server.crt \
--form '[email protected]"<PATH-TO-YOUR-PUBLIC-GPG-KEY>/pubkey.gpg"'

Install your extension on the EDK-ERE.

curl --location --request POST 'https://localhost:5001/extensions' \
--header 'Authorization: Bearer <YOUR-JWT>' \
--cacert cert/server.crt \
--form '[email protected]"<PATH-TO-YOUR-PACKAGE>/<NAME-OF-YOUR-PACKAGE>.tar.gz.gpg"'

Set up EclecticIQ Intelligence Center#

In order for your extension to appear in EclecticIQ Intelligence Center, perform the following steps.

Requirements:

EclecticIQ Intelligence Center 3.0 and newer
Root access on the EclecticIQ Intelligence Center host

Configuration:

To allow EclecticIQ Intelligence Center to connect to the EDK, you must configure the EclecticIQ Intellince Center:

Sign in to EclecticIQ Intelligence Center.
From the left navigation, select Settings > EclecticIQ Labs.
Select the toggle to the left of Extensions Developer Kit.

In the panel that appears, configure the following fields. Use the values from the .env file you set up earlier.

Note

* Required fields

Field name	Description
Subject*	Set this to the value used for `EIQ_EDK_VALID_AUTH_TOKEN_SUBJECT`.
URL*	Fully qualified URL to EDK Management API service. E.g. https://edk.example.com:5001.
Role*	Set this to the value used for `EIQ_EDK_MANAGEMENT_APP_ROLE`.
Secret*	Set this to the value used for `EIQ_EDK_MANAGEMENT_APP_JWT_SECRET_KEY`.
Verify	(Recommended) Select Yes to enforce SSL verification.
Custom SSL	File path to custom certificate file to use when connecting to the EDK management API.

Restart services on the EclecticIQ Intelligence Center host. Run as root:

Tip

If you are running a multi-node IC cluster, you must perform these steps on all hosts/nodes that run the EclecticIQ Intelligence Center application.
```
systemctl restart eclecticiq-platform-backend-services
```