Skip to content

Latest commit

 

History

History
300 lines (232 loc) · 9.2 KB

README.md

File metadata and controls

300 lines (232 loc) · 9.2 KB
Raw

Archimate container image for CI

Archi container image for use in continuous integration pipelines. With this container, you can implement automatic report generation and model export in your pipeline.

The Archi modelling toolkit is targeted toward all levels of Enterprise Architects and Modellers.

For collaboration with models in the git repository, the coArchi plugin is installed in the container.

For ease of use, the entrypoint.sh script is run in the container, which processes the environment variables, and the native git client is used for cloning.

Table of Contents

Examples and Demo

View GitHub Pages demo | Example GitHub repository

View GitLab Pages demo | Example GitLab repository

Container image

You can pull image from registries:

  • ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4
  • docker.io/woozymasta/archimate-ci-image:5.0.2-1.0.4

And rootless image:

  • ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4-rootless
  • docker.io/woozymasta/archimate-ci-image:5.0.2-1.0.4-rootless

Run Container

Example with cloning a remote repository and render HTML report:

mkdir -p ./report
chmod o+rw ./report

docker run --rm -ti \
  -v $(pwd)/report:/archi/report \
  -e GIT_REPOSITORY=https://github.com/WoozyMasta/archimate-ci-image-example.git \
  -e ARCHI_HTML_REPORT_ENABLED=true \
  -e ARCHI_JASPER_REPORT_ENABLED=false \
  -e ARCHI_CSV_REPORT_ENABLED=true \
  -e ARCHI_EXPORT_MODEL_ENABLED=true \
  ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4

An example with handling a local repository:

cd /path/to/exist/repository
mkdir -p ./report
chmod o+rw ./report

docker run --rm -ti \
  -v $(pwd):/archi/project \
  -v $(pwd)/report:/archi/report \
  ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4

Working with the CLI directly:

docker run --rm -ti ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4 --help

Example on how to write preferences:

mkdir -p ./settings

# Change the setting to increase the resolution of the images in the HTML report.

cat << EOF > ./settings/com.archimatetool.editor.prefs
eclipse.preferences.version=1
scaleImageExport=true
EOF

docker run --rm -ti \
  -v $(pwd)/settings:/root/.archi/.metadata/.plugins/org.eclipse.core.runtime/.settings \
  ...

Configuration

Configuration for connecting to the git repository:

  • GIT_REPOSITORY - Git repository address;
  • GIT_TOKEN - Token for accessing the git repository. Preferred for private repositories, or use a key mounted in an ssh container;
  • GIT_USERNAME - Username (it is better to use token or ssh key);
  • GIT_PASSWORD - Password (it is better to use token or ssh key).

Options for managing model export:

  • ARCHI_PROJECT_PATH=/archi/project - The path where the git repository with the architectural model will be cloned or connected;
  • ARCHI_REPORT_PATH=/archi/report - Path where reports will be saved;
  • ARCHI_HTML_REPORT_ENABLED=true - Generate HTML report;
  • ARCHI_HTML_REPORT_PATH=$ARCHI_REPORT_PATH/html - Path for save HTML report;
  • ARCHI_JASPER_REPORT_ENABLED=false - Generate Jasper reports;
  • ARCHI_JASPER_REPORT_PATH=$ARCHI_REPORT_PATH/jasper - Path for save Jasper report;
  • ARCHI_JASPER_REPORT_FORMATS=PDF,DOCX - Formats for Jasper reports should be separated by commas. Valid values: PDF, HTML, RTF, PPT, ODT, DOCX;
  • ARCHI_JASPER_REPORT_TITLE - The title for the Jasper report, the default is the model/project name;
  • ARCHI_CSV_REPORT_ENABLED=false - Generate CSV report;
  • ARCHI_CSV_REPORT_PATH=$ARCHI_REPORT_PATH/csv - Path for save CSV report;
  • ARCHI_EXPORT_MODEL_ENABLED=true - Export model in *.archimate format.
  • ARCHI_EXPORT_MODEL_PATH=$ARCHI_REPORT_PATH - Path for save model;
  • ARCHI_APP=com.archimatetool.commandline.app application name.
  • DEBUG=false - enable bash -x

GitHub Actions Configuration

Variables

  • GITHUB_TOKEN - Use default token, or you can set some token from secrret ${{ secrets.ACCESS_TOKEN }}
  • GITHUB_SERVER_URL=https://github.com - GitHub server URL;
  • GITHUB_PAGES_DOMAIN - Custom domain CNAME for pages;
  • GITHUB_PAGES_BRANCH=gh-pages - Branch for store reports used in pages;
  • GIT_SUBTREE_PREFIX=.archi_report - Directory for store reports in model branch.

Inputs

All inputs equivalent to environment variables:

  • githubToken required
  • archiHtmlReportEnabled
  • archiJasperReportEnabled
  • archiJasperReportFormats
  • archiJasperReportTitle
  • archiCsvReportEnabled
  • archiExportModelEnabled
  • githubServerURL
  • githubPagesDomain
  • githubPagesBranch
  • gitSubtreePrefix
  • debugAction

GitHub Actions Example

Add a configuration like this to your actions .github/workflows/main.yml file:

jobs:
  archi_report:
    permissions:
      contents: write
      pages: write
    runs-on: ubuntu-latest
    name: Deploy Archi report HTML to GitHub Pages
    steps:
      - name: Check out the repo
        uses: actions/checkout@v2

      - name: Deploy Archi report
        id: archi
        uses: WoozyMasta/[email protected]
        with:
          archiHtmlReportEnabled: true
          archiJasperReportEnabled: true
          archiJasperReportFormats: PDF,DOCX
          archiCsvReportEnabled: false
          archiExportModelEnabled: true
          githubToken: ${{ secrets.GITHUB_TOKEN }}

In the repository settings, set the branch for publishing pages that you specified in githubPagesBranch or the GITHUB_PAGES_BRANCH variable (gh-pages by default).

pages

GitLab CI Example

Add a configuration like this to your ./.gitlab-ci.yml file:

pages:
  stage: build
  image:
    name: ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4
    entrypoint: [""]

  script:
    - /opt/Archi/entrypoint.sh
    
  variables:
    ARCHI_HTML_REPORT_ENABLED: "true"
    ARCHI_JASPER_REPORT_ENABLED: "true"
    ARCHI_JASPER_REPORT_FORMATS: "PDF,DOCX"
    ARCHI_CSV_REPORT_ENABLED: "false"
    ARCHI_EXPORT_MODEL_ENABLED: "true"

  rules:
    - if: $CI_COMMIT_BRANCH != null || $CI_PIPELINE_SOURCE == "merge_request_event"
      exists:
        - model/folder.xml

  artifacts:
    name: "$CI_JOB_NAME from $CI_PROJECT_NAME on $CI_COMMIT_REF_SLUG"
    expire_in: 30d
    paths:
      - public

In GitLab CI if ARCHI_PROJECT_PATH is undefined is set to $CI_PROJECT_DIR and all report paths are automatically set to $CI_PROJECT_DIR/public

Build Container

ARCHI_VERSION=5.0.2
COARCHI_VERSION=0.8.7

docker build \
  --tag "archimate-ci-image:$ARCHI_VERSION-dev" \
  --build-arg="ARCHI_VERSION=$ARCHI_VERSION" \
  --build-arg="COARCHI_VERSION=$COARCHI_VERSION" \
  ./

docker build \
  --file Dockerfile.rootless \
  --tag "archimate-ci-image:$ARCHI_VERSION-dev-rootless" \
  --build-arg="ARCHIMATE_CI_IMAGE=archimate-ci" \
  --build-arg="ARCHIMATE_CI_VERSION=$ARCHI_VERSION-dev" \
  ./

Solving Potential Problems

If you use podman, unshare mounted volumes to user with id 1000.

mkdir -p ./report

podman unshare chown 1000 -R $(pwd)/model
podman run --rm -ti \
  -v $(pwd)/report:/archi/report \
  -e GIT_REPOSITORY=https://github.com/WoozyMasta/archimate-ci-image-example.git \
  -e ARCHI_JASPER_REPORT_ENABLED=false \
  ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4

If you are using a private git repository hosted behind a VPN, the tunnel interface or name resolution might not be available in the container, use the host network in the container and force the DNS record forward.

docker run --rm -ti \
  -v $(pwd)/archi:/archi \
  -e GIT_REPOSITORY=https://github.com/WoozyMasta/archimate-ci-image-example.git
  --network=host
  --add-host="$(getent hosts gitlab.internal.tld | awk '{print $2 ":" $1}')"
  ghcr.io/woozymasta/archimate-ci-image:5.0.2-1.0.4