Skip to content

Latest commit

 

History

History
125 lines (81 loc) · 4.84 KB

PREREQUISITES.md

File metadata and controls

125 lines (81 loc) · 4.84 KB
Raw

Run Epicli from Docker image

There are 2 ways to get the image, build it locally yourself or pull it from the Epiphany docker registry.

Build Epicli image locally

  1. Install the following dependencies:

    • Docker

  2. Open a terminal in the root directory of the Epiphany repository:

TAG=$(cat VERSION)
docker build --file Dockerfile --tag epicli:${TAG} .

Pull Epicli image from the registry

docker pull ghcr.io/hitachienergy/epicli:TAG

Where TAG should be replaced with an existing tag.

Check here for the available tags.

Running the Epicli image

To run the image:

docker run -it -v LOCAL_DIR:/shared --rm ghcr.io/hitachienergy/epicli:TAG

Where:

  • LOCAL_DIR should be replaced with the local path to the directory for Epicli input (SSH keys, data yaml files) and output (logs, build states),
  • TAG should be replaced with an existing tag.

Check here for the available tags.

Epicli development

For setting up en Epicli development environment please refer to this dedicated document here.

Important notes

Hostname requirements

Epiphany supports only a lowercase RFC 1123 subdomain that must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character.

Note for Windows users

  • Watch out for the line endings conversion. By default, Git for Windows sets core.autocrlf=true. Mounting such files with Docker results in ^M end-of-line character in the config files. Use: Checkout as-is, commit Unix-style (core.autocrlf=input) or Checkout as-is, commit as-is (core.autocrlf=false). Be sure to use a text editor that can work with Unix line endings (e.g. Notepad++).

  • Remember to allow Docker Desktop to mount drives in Settings -> Shared Drives

  • Escape your paths properly:

    • Powershell example:
    docker run -it -v C:\Users\USERNAME\git\epiphany:/epiphany --rm epiphany-dev:
    • Git-Bash example:
    winpty docker run -it -v C:\\Users\\USERNAME\\git\\epiphany:/epiphany --rm epiphany-dev

  • Mounting NTFS disk folders in a linux based image causes permission issues with SSH keys. When running either the development or deploy image:

  1. Copy the certs on the image:

    mkdir -p ~/.ssh/epiphany-operations/
cp /epiphany/core/ssh/id_rsa* ~/.ssh/epiphany-operations/

  2. Set the proper permission on the certs:

    chmod 400 ~/.ssh/epiphany-operations/id_rsa*

Note about proxies

To run Epicli behind a proxy, environment variables need to be set.

When running a development container (upper and lowercase are needed because of an issue with the Ansible dependency):

export http_proxy="http://PROXY_SERVER:PORT"
export https_proxy="https://PROXY_SERVER:PORT"
export HTTP_PROXY="http://PROXY_SERVER:PORT"
export HTTPS_PROXY="https://PROXY_SERVER:PORT"

Or when running from a Docker image (upper and lowercase are needed because of an issue with the Ansible dependency):

docker run -it -v POSSIBLE_MOUNTS... -e HTTP_PROXY=http://PROXY_SERVER:PORT -e HTTPS_PROXY=http://PROXY_SERVER:PORT http_proxy=http://PROXY_SERVER:PORT -e https_proxy=http://PROXY_SERVER:PORT --rm IMAGE_NAME

Note about custom CA certificates

In some cases it might be that a company uses custom CA certificates or CA bundles for providing secure connections. To use these with Epicli you can do the following:

Devcontainer

Note that for the comments below the filenames of the certificate(s)/bundle do not matter, only the extensions. The certificate(s)/bundle need to be placed here before building the devcontainer.

  1. If you have one CA certificate you can add it here with the crt extension.
  2. If you have multiple certificates in a chain/bundle you need to add them here individually with the crt extension and also add the single bundle with the pem extension containing the same certificates. This is needed because not all tools inside the container accept the single bundle.

Epicli release container

If you are running Epicli from one of the prebuilt release containers you can do the following to install the certificate(s):

cp ./path/to/*.crt /usr/local/share/ca-certificates/
chmod 644 /usr/local/share/ca-certificates/*.crt
update-ca-certificates

If you plan to deploy on AWS you also need to add a separate configuration for Boto3 which can either be done by a config file or setting the AWS_CA_BUNDLE environment variable. More information about for Boto3 can be found here.