Deploy Base ArcGIS Enterprise on Windows in AWS - Esri/arcgis-gitops GitHub Wiki

This walkthrough will guide you through the process of initial deployment of a standalone highly available base ArcGIS Enterprise on Windows Server 2022 operating system in Amazon Web Services (AWS) using GitHub Actions.

The walkthrough uses aws/arcgis-enterprise-base-windows template.

Duration: about 4 hours

Prerequisites

Before you begin this walkthrough:

  • A private GitHub repository "gitops-demo" for the site must be created and properly configured.
  • The core resources for the ArcGIS Enterprise site must be provisioned in the AWS account.

Refer to the Getting Started in AWS walkthrough for detailed instructions.

You will need the following resources and accounts:

  • GitHub.com user account
  • Access keys of an AWS user with permissions to create and update IAM users, TLS/SSL certificates, S3 buckets, EC2 instances, and SSM parameters (IAMFullAccess, AWSCertificateManagerFullAccess, AmazonS3FullAccess, AmazonEC2ReadOnlyAccess, and AmazonSSMFullAccess AWS managed IAM policies)
  • Software authorization files for ArcGIS Server and Portal for ArcGIS 11.4
  • Domain name for the ArcGIS Enterprise site
  • SSL/TLS certificate for the ArcGIS Enterprise site domain name

Step 1: Create and Configure a Codespace Workspace

This step creates a codespace workspace in the "gitops-demo" repository, installs AWS CLI v2, and configures it with the AWS account access keys.

1.1 Log in to GitHub.com account

Open the GitHub.com URL in a web browser, log in to your GitHub.com account, and select "gitops-demo" private repository form the "Your repositories" list.

1.2 Create a codespace workspace in the new repository

In the "gitops-demo" repository, click the green "Code" button, switch to the "Codespaces" tab, and click the "Create codespace on main" button. The codespace will be created and opened in a new browser tab.

Create codespace

Note that instead of creating a codespace, you can also reuse the codespace created in Getting Started in AWS walkthrough if it is still available. In this case, you can skip this step and go to Step 1.5.

1.3 Install AWS CLI v2 in the codespace

In the codespace, click on the "Terminal" tab in the bottom panel, and run the following commands:

cd /tmp

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"

unzip awscliv2.zip

sudo ./aws/install

Output:

You can now run: /usr/local/bin/aws --version

1.4 Configure the AWS CLI

Run the following commands and enter the AWS account user's access keys and the default AWS region ID when prompted:

aws configure

1.5 Install the Session Manager plugin for the AWS CLI

Session Manager plugin is required to use AWS Systems Manager (SSM) Session Manager to connect to the EC2 instances of the deployment.

Run the following commands in the codespace terminal:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"

sudo dpkg -i session-manager-plugin.deb

Step 2: Enable the Required Workflows

This step enables all the arcgis-enterprise-base-windows template workflows by copying them to .github/workflows directory and attaches the required IAM policies to gitops-demo IAM user.

2.1 Copy the required workflows to .github/workflows directory

Switch back to the codespace browser tab and run the following commands:

cd /workspaces/gitops-demo

cp -r aws/arcgis-enterprise-base-windows/workflows/* .github/workflows/

git add --all

git commit -m "Enable arcgis-enterprise-base-windows workflows"

git push origin main

2.2 Attach the policies to the IAM user

Attach the policies required for running the workflows used by this walkthrough to gitops-demo IAM user.

export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

aws iam attach-user-policy --policy-arn arn:aws:iam::$AWS_ACCOUNT_ID:policy/ArcGISEnterpriseApplication --user-name gitops-demo

aws iam attach-user-policy --policy-arn arn:aws:iam::$AWS_ACCOUNT_ID:policy/ArcGISEnterpriseImage --user-name gitops-demo

aws iam attach-user-policy --policy-arn arn:aws:iam::$AWS_ACCOUNT_ID:policy/ArcGISEnterpriseInfrastructure --user-name gitops-demo

Step 3: Set Secrets and Update Config Files

This step sets the GitHub Actions secrets, updates the configuration files used by the template workflows, uploads the required software authorization files, pushes the changes to the main brunch of the repository, and verifies the site configuration.

3.1 Configure GitHub Actions secrets

Open the new repository settings by clicking on the Settings tab in the repository, then click on "Secrets and Variables" menu item from "Security" section of the left sidebar, and select "Actions" from the dropdown menu.

  • Click on "New repository secret" button, enter ENTERPRISE_ADMIN_USERNAME into the "Name" field, enter the ArcGIS Enterprise administrator user name into the "Value" field, and click "Add secret" button.

    The user name must be between 6 and 128 characters long and can consist only of uppercase and lowercase ASCII letters, numbers, and dots (.).

  • Add ENTERPRISE_ADMIN_PASSWORD secret with the ArcGIS Enterprise administrator user password.

    The password must be between 8 and 128 characters long and can consist only of uppercase and lowercase ASCII letters, numbers, and dots (.).

  • Add ENTERPRISE_ADMIN_EMAIL secret with the ArcGIS Enterprise administrator e-mail address.
  • Add RUN_AS_PASSWORD secret with password of 'arcgis' windows user account.

    The password must be at least 8 characters long, include at least three of the four character types: uppercase letters, lowercase letters, numbers, and special characters. Additionally, passwords should not contain the account name ('arcgis').

3.2 Update image.vars.json file

Update config/aws/arcgis-enterprise-base-windows/image.vars.json config file to specify the ArcGIS Enterprise version and patches to be installed.

In EXPLORER sidebar of the codespace window, click on "config" folder, then on "aws" subfolder, and then on "arcgis-enterprise-base-windows" subfolder. Double-click on "image.vars.json" file to open it in the editor.

  • Change "arcgis_version" value to "11.4".

3.3 Import the SSL/TLS certificate for ArcGIS Enterprise site domain name to AWS Certificate Manager

Upload the SSL certificate files to the /workspaces/gitops-demo/config/certificates directory in the workspace.

In the EXPLORER sidebar of the codespace window, click on "config" folder, then right-click on "certificates" folder, and select "Upload..." from the context menu. In the file selector dialog window navigate to the SSL certificate files location, select the certificate, private key and chain files, and click "Open" button to upload the files.

Run the following command in the codespace Terminal replacing arcgis-enterprise.crt, arcgis-enterprise.key, and arcgis-enterprise.ca-bundle by the uploaded file names:

cd /workspaces/gitops-demo/config/certificates

aws acm import-certificate --certificate fileb://arcgis-enterprise.crt --private-key fileb://arcgis-enterprise.key --certificate-chain fileb://arcgis-enterprise.ca-bundle --tags Key=ArcGISSiteId,Value=arcgis

Output:

{
    "CertificateArn": "arn:aws:acm:us-west-2:012345678900:certificate/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}

Alternatively, you can provision the SSL certificate using AWS Certificate Manager.

3.4 Update infrastructure.tfvars.json file

Open config/aws/arcgis-enterprise-base-windows/infrastructure.tfvars.json file in the editor and update the following properties:

  • Replace the "deployment_fqdn" property value by the base ArcGIS Enterprise deployment fully qualified domain name.
  • Replace the "ssl_certificate_arn" property value by the imported SSL certificate ARN.

3.5 Update application.tfvars.json file

Upload the ArcGIS Server and Portal for ArcGIS 11.4 authorization files to the "config/authorization/11.4/" directory in the codespace workspace.

In the EXPLORER sidebar of the codespace window, click on "config" folder, then right-click on "authorization" folder, select "New Folder..." from the context menu, and enter "11.4" as the folder name. Right-click on the new "11.4" folder, and select "Upload..." from the context menu. In the file selector dialog window navigate to the authorization files location, select the files, and click "Open" button to upload the files to the workspace.

Open config/aws/arcgis-enterprise-base-windows/application.tfvars.json file in the editor and update the following properties:

  • Change "arcgis_version" value to "11.4".
  • Replace "portal_authorization_file_path" property to the uploaded authorization file paths "~/config/authorization/11.4/<portal authorization file name>".
  • Replace "server_authorization_file_path" property to the uploaded authorization file paths "~/config/authorization/11.4/<server authorization file name>".
  • Replace "admin_full_name", "admin_description", "security_question", and "security_question_answer" to the initial ArcGIS Enterprise administrator account properties.

The workflows link '~/config/' paths to the repository's 'config/' directory.

3.6 Update site-index.json file

Replace the "deployments" property value in config/aws/site-index.json file by ["arcgis-enterprise-base-windows"].

3.7 Commit and push the changes to the repository

git add --all

git commit -m "Update arcgis-enterprise-base-windows config"

git push origin main

3.8 Verify the configuration files

Run "verify-site-config-aws" workflow to verify the site configuration.

Click on "Actions" tab in the repository, select "verify-site-config-aws" workflow on the left sidebar, click "Run workflow" on the right, and click "Run workflow" button.

Step 4: Deploy Base ArcGIS Enterprise

This step runs the workflows build base ArcGIS Enterprise AMI, provision AWS resources for the deployment, configure base ArcGIS Enterprise, test and backup the deployment.

4.1 Build base ArcGIS Enterprise AMI

Run "enterprise-base-windows-aws-image" workflow that creates EC2 AMI for the base ArcGIS Enterprise deployment.

Wait for the workflow run to complete.

4.2 Provision AWS Resources for the base ArcGIS Enterprise deployment

Run "enterprise-base-windows-aws-infrastructure" workflow that creates AWS resources for the base ArcGIS Enterprise deployment.

After the workflow run is complete, retrieve the DNS name of the load balancer created by the workflow from SSM Parameter Store:

aws ssm get-parameter --name "/arcgis/arcgis/enterprise-base-windows/alb/dns-name" --query "Parameter.Value" --output text

Create a CNAME record for the load balancer DNS name in the DNS server managing the base ArcGIS Enterprise domain name.

4.3 Configure the base ArcGIS Enterprise deployment

Run "enterprise-base-windows-aws-application" workflow to configure the base ArcGIS Enterprise deployment.

After the workflow run is complete, the base ArcGIS Enterprise deployment will be accessible at https://<deployment FQDN>/portal.

4.4 Test the deployment

Run "enterprise-base-windows-aws-test" workflow.

4.5 Apply workaround for BUG-000171297

The Web GIS Disaster Recovery (WebGISDR) tool used by "enterprise-base-windows-aws-backup" and "enterprise-base-windows-aws-restore" workflow fails to run with Portal for ArcGIS 11.4 when storing the backup in an S3 bucket. See BUG-000171297 for details.

Before using these workflows, you need to copy the azure-storage-file-datalake.jar file from the Portal for ArcGIS framework\lib directory into the tools\webgisdr\lib directory on the primary EC2 instance of the deployment.

List the EC2 instances of the deployment:

aws ec2 describe-instances --filters "Name=tag:ArcGISSiteId,Values=arcgis"  --filters "Name=tag:ArcGISDeploymentId,Values=enterprise-base-windows" --query "Reservations[*].Instances[*].{Instance:InstanceId,Name:Tags[?Key=='Name']|[0].Value}"

Start an SSM session with the "arcgis/enterprise-base-windows/primary" EC2 instance using Session Manager:

aws ssm start-session --target <instance-id>

Output:

Starting session with SessionId: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Run the following command in the SSM session to copy the azure-storage-file-datalake.jar file from the Portal for ArcGIS framework\lib directory into the tools\webgisdr\lib directory.

Copy-Item "C:\Program Files\ArcGIS\Portal\framework\lib\azure-storage-file-datalake.jar" "C:\Program Files\ArcGIS\Portal\tools\webgisdr\lib"

Exit the SSM session:

exit

4.6 Backup the deployment

Run "enterprise-base-windows-aws-backup" workflow.

arcgis-enterprise-base-windows template workflows

4.7 Open the deployment's CloudWatch dashboard

Sign in to the AWS Console and open the URL https://console.aws.amazon.com/cloudwatch/home?#dashboards:name=arcgis-enterprise-base-windows in a web browser.

Conclusion

The walkthrough demonstrates only the basic capabilities of ArcGIS Automation using GitHub Actions. Check instructions of the templates and workflows for more advanced features and options.

Next steps:

Follow Destroy Base ArcGIS Enterprise on Windows in AWS walkthrough to destroy the deployment and clean up the resources created during this walkthrough.