pyATS の GUI である XPRESSO をインストールする

XPRESSO はネットワークテストの自動化ツールである pyATS にブラウザからアクセス可能な UI を提供します。 今回は XPRESSO のインストール手順をメモしておきます。 尚、タイムゾーンの指定など、設定に関しては省略しており、インストール手順までだけをメモしています。

要求スペック

Requirements に要求スペックは以下と記載されていました。 スペックの低い環境で動作させると「一部のコンテナが正常に起動しない」等の状態になるようです (なりました)。

• Linux/macOS environment
• Docker installed and in working condition
• Free disk space for log storage
• Minimum System Spec:
  • 4 CPU (with hyper-threading)
  • 16G memory
• Ideal System Spec:
  • 12 CPU
  • 64G memory

上記も踏まえ、今回は以下の環境で検証しました。

• Ubuntu 22.04LTS
• 12CPU
• 16GB Memory

Docker Engine / Docker Compose のインストール

今回は Docker Compose を使い、XPRESSO をコンテナとして動作させますので、予め Docker Engine / Docker Compose をインストールしておきます。 Ubuntu への Docker インストール手順は過去に書いた以下のメモ、または公式サイトを参考にします。

• Install Docker Engine on Ubuntu ※ 公式サイト
• Ubuntu 22.04.2LTS へ docker / docker-compose / docker-purge をインストールする

公式サイトの手順では Docker Engine と共に Docker Compose もパッケージでインストールしているのですが、現時点でパッケージ版のバージョンは 2.21.0 でした。 Docker Compose の GitHub にある最新版はバージョの 2.23.0 なので (公式サイトでは無い) 私のメモでは「Docker Compose は別途、GitHub からインストールする」手順にしています。

vm.max_map_count の拡張

GitHub に注意点として下記が記載されています。

[ WARNING ]: in linux servers, make sure the max_map_count is set to at least 262144, ie vm.max_map_count=262144. See elastic documentation for details.

また、XPRESSO の Issue に登録されている admin/admin not working #45 は「初期ユーザでログイン出来ない」というものですが、この Issue には以下と書かれています。

Reboot your server and than start again the EXpresso as advised in the § 4. "Start you engine" in the https://github.com/CiscoTestAutomation/xpresso#readme After that I was able to log in as described. The reboot may be especially important if the initial setup modified the sysctl.conf file (vm.max_map_count=262144) and if during the first start-up a lot of updates was installed.

XPRESSO は内部的に Elastic を利用している為、上述の通り vm.max_map_count の値を増やす必要があります。 XPRESSO には後述するセットアップスクリプト (setup.sh) が同梱されており、このスクリプト内で vm.max_map_count を修正することは可能なのですが、同スクリプト中では「値の修正は行っているが、反映はしていない」状態のようです。 その為、予め手動で vm.max_map_count を修正しておきます。 私の環境ではデフォルト値は 65,530 でした。

# sysctl -n vm.max_map_count
65530

XPRESSO (や Elastic) のドキュメントに書かれている内容に従って vm.max_map_count の値を増やします。

echo 'vm.max_map_count=262144' >> /etc/sysctl.conf
sysctl -p

XPRESSO のインストール

XPRESSO をインストールします。 まず、GitHub からダウンロードします。

git clone https://github.com/CiscoTestAutomation/xpresso
cd xpresso/

過去、docker compose のバイナリは docker-compose という独立したバイナリでしたが、現在は docker compose のように「docker のサブコマンド」として動作します。 XPRESSO にはセットアップスクリプトである setup.sh が同梱されていますが、このスクリプト中では過去の形式である docker-compose を前提にかかれています。 以下のように実行し、この部分を「docker-compose → docker compose」へ置換します。

sed -i -e "s/docker-compose/docker compose/g" setup.sh

セットアップスクリプトを実行します。 セットアップスクリプトには引数として「外部からアクセスさせたい URL」(ADVERTISED_URL) を指定して実行します。 途中で「vm.max_map_count を修正するか？」と問われますが、事前に手動で修正・反映している為、ここでは no を入力して続行します。 必要なコンテナイメージをダウンロードするので実行完了までしばらく時間がかかります。

# ./setup.sh http://10.0.0.1/
ADVERTISED_URL: http://10.0.0.1/
Do you wish to continue? yes

Creating data and logs directory
Warning:
Elasticsearch uses a mmapfs directory by default to store its indices. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions.
Visit: https://www.elastic.co/guide/en/elasticsearch/reference/master/_maximum_map_count_check.html
Writing 'vm.max_map_count=262144' to '/etc/sysctl.conf'
Do you wish to edit /etc/sysctl.conf?no
Initialization of Setup complete!
Bringing up the database....
・
・
・
 ✔ Container xpresso-database-1    Running                                                                                              0.0s
 ✔ Container xpresso-cache-1       Running                                                                                              0.0s
 ✔ Container xpresso-management-1  Started                                                                                              9.7s
run: 'docker compose up -d' to start xpresso.

いよいよコンテナを起動させます。 GitHub の 4. Start Your Engine に下記のように記載されています。

It may take a while for the initial settings to be automatically applied while the system boots for the first time. This may mean you could not login using the default credentials for a few minutes. Give it some time (eg, 5-10min on a 2016 MacBook Pro 15)

その為、実行環境のスペックに依存すると思われますが、コンテナ起動直後しばらく (10 〜 15 分程度？) は放置しておき、初期化作業が完了するまで待った方が良いかもしれません。 Docker Compose でコンテナを起動させ、私の場合は 15 分程度放置しておきました。

docker compose up -d

XPRESSO へのログイン

セットアップスクリプト実行時に ADVERTISED_URL として指定した URL へブラウザでアクセスすると XPRESSO の画面が表示されます。 画面右上の Login をクリックします。

ログイン画面が表示されます。

デフォルトのログイン情報は以下です (ユーザ名・パスワードの両方とも admin)。

	初期ユーザ名	初期パスワード
値	admin	admin

ユーザ名とパスワードを入力したログインします。

初回ログイン時はドキュメントが表示されるようです。

以降は Requests の画面が表示されました。

参考

初期状態の setup.sh

RED='\033[0;31m'
YLW='\033[0;33m'
BLUE='\033[0;34m'
GREEN='\033[0;32m'
NC='\033[0m' # No Color



echo -e "ADVERTISED_URL: ${BLUE}$1${NC}";
[ -z "$1" ] && echo "ADVERTISED_URL not set. Enter the host url you would like to advertise." && exit;

while true; do
    read -p "Do you wish to continue? " yn
    case $yn in
        [Yy]* ) break;;
        [Nn]* ) exit;;
        * ) echo "Please answer yes or no.";;
    esac
done


if [[ "$1" == */ ]]; then
   echo ""
else
   echo -e "${RED}'/'  not exists in the end in your given url.${NC}"
   exit
fi


# comment this for mac OS
# sed -i .bak '/ADVERTISED_URL/d' ./.env;

sed -i '/ADVERTISED_URL/d' ./.env;
echo "ADVERTISED_URL=$1" >> ./.env;


echo 'Creating data and logs directory';

mkdir logs
mkdir logs/database
chmod 777 -R  logs
mkdir data
mkdir data/elastic
mkdir data/elastic_snapshots
mkdir data/mysql
chmod 777 -R  data

echo -e "${YLW}Warning:${NC}";
echo -e "${YLW}Elasticsearch uses a mmapfs directory by default to store its indices. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions. \nVisit: https://www.elastic.co/guide/en/elasticsearch/reference/master/_maximum_map_count_check.html${NC}";
echo -e "${RED}Writing 'vm.max_map_count=262144' to '/etc/sysctl.conf'${NC}";

while true; do
    read -p "Do you wish to edit /etc/sysctl.conf?" yn
    case $yn in
        [Yy]* ) sed -i '/max_map_count/d' /etc/sysctl.conf; echo 'vm.max_map_count=262144' >> /etc/sysctl.conf; echo "file written"; break;;
        [Nn]* ) break;;
        * ) echo "Please answer yes or no.";;
    esac
done


echo -e "${GREEN}Initialization of Setup complete!${NC}";

echo -e "${YLW}Bringing up the database....${NC}";
docker-compose up -d database cache elasticsearch

sleep 50

echo -e "${YLW}Bringing up the management service....${NC}";

docker-compose up -d  management

sleep  20

echo -e "${GREEN}run: 'docker-compose up -d' to start xpresso.${NC}";