Skip To Content

Deploy a single-machine ArcGIS GeoEvent Server site using CloudFormation

The Esri arcgis-geoevent-server-singlemachine.template.json Amazon Web Services (AWS) CloudFormation template creates an ArcGIS GeoEvent Server site on a single Amazon Elastic Compute Cloud (EC2) instance.

This template creates the following architecture in Amazon Web Services:

ArcGIS GeoEvent Server site on one EC2 instance with an optional Elastic IP and web adaptor

License:

Certain icons in the diagram are used with permission from Amazon Web Services.

Prerequisites

Prerequisites can be grouped by the items—such as files and accounts—that you must obtain and the tasks you must perform before running the CloudFormation template.

Required items

You need the following before running this template:

  • An Amazon Web Services account.

    The account must have access to basic AWS services such as CloudFormation, Amazon Elastic Compute Cloud (EC2), Amazon Virtual Private Cloud (VPC), Amazon Simple Storage Service (S3), Systems Manager, Amazon CloudWatch, Lambda, AWS Identity and Access Management (IAM), Amazon DynamoDB, Secrets Manager, AWS Certificate Manager, and Amazon Relational Database Service (RDS).

  • An SSL certificate file (in .pfx format) and corresponding password.

    The certificate must be from a certifying authority.

  • An Amazon Virtual Private Cloud (VPC) and subnets.

    If you are creating a stand-alone site, you can use one of the following CloudFormation templates to create a VPC: VPC with two public subnets or VPC with two public and private subnets with a NAT Gateway.

    If you intend to federate this site with an ArcGIS Enterprise portal, ensure that all components in the same ArcGIS Enterprise deployment run in the same VPC.

  • An ArcGIS GeoEvent Server license file (.ecp or .prvc).
  • If you create a deployment on Ubuntu EC2 instances in AWS GovCloud, you need an AMI ID. If you want to use the base canonical Ubuntu AMI, follow the instructions in Esri Amazon Web Services CloudFormation templates to identify the ID.
  • The CloudFormation template.

    Open and save a local copy of the arcgis-geoevent-server-singlemachine.template.json template.

Required tasks

Complete the following tasks before running this template:

  • Prepare a deployment Amazon Simple Storage Service (S3) bucket in the AWS account. Specify the bucket name in the template when you launch the stack.
    1. Create a bucket or use an existing S3 bucket. You must be the owner of the bucket.
    2. Upload the ArcGIS GeoEvent Server authorization file to the bucket.
    3. Upload the SSL certificate file to the deployment bucket.
  • Configure a Domain Name System (DNS).

    You must have a fully qualified domain name for the ArcGIS GeoEvent Server site. This domain name must exist before you launch this stack, and it must be resolvable. Contact your IT department if you are unsure how to obtain a fully qualified domain name and configure a DNS.

  • If you use an Elastic IP address with this deployment (optional), you must create the Elastic IP address before running this template.

    You can use AWS Management Console to create the Elastic IP address.

  • Configure passwords in AWS Secrets Manager (optional but recommended).

    You can configure the passwords for accounts such as the site administrator user name and the Windows arcgis user password in AWS Secrets Manager. This provides you with a secret Amazon Resource Name (ARN). Use the ARN in place of a password in the template parameters when you launch a stack. If you don't use AWS Secrets Manager for storing passwords, you must type passwords in plain text in the template parameter when launching the stack.

    Note:

    When creating a secret ARN in AWS Secrets Manager for a password to be used with Esri CloudFormation templates, you must use the Other types of secrets secret type and use the Plaintext option. For more information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS.

Tip:

By default, CloudFormation deletes partially created resources if stack creation fails. This is helpful because it removes unusable deployments from your account, but it can make it difficult to troubleshoot. To retain the stack in its failed state, disable the Rollback on failure CloudFormation stack creation option before launching the stack. See Setting AWS CloudFormation options in the AWS help for more information.

Parameters

Refer to the following tables for descriptions of the parameters used in this CloudFormation template. Tables are grouped by parameter type.

Amazon EC2 Configuration

Parameter nameRequired?Parameter description

Platform Type

Required

Choose the operating system platform. Supported types are as follows:

  • Windows (Windows Server 2019)
  • Linux ( Ubuntu Server 18.0.4 LTS)

EC2 Instance AMI ID

Optional

You can leave this parameter value empty. If you do, CloudFormation templates will use the latest Amazon Machine Image (AMI) ID for Windows or Ubuntu based on the type of platform you selected.

Note:

You cannot leave this parameter empty if you deploy in AWS GovCloud on an Ubuntu Server. See Esri Amazon Web Services CloudFormation templates for instructions on finding the ID for the base Ubuntu AMI from Canonical.

The first time you use one of the default AMIs for a specific release, you must accept AWS Marketplace terms.

If you want to use your own custom AMI, you can type the AMI ID using one of the following:

  • Provide the AMI ID in the format 'ami-xxxxx'.
  • If you stored the AMI ID in the AWS SSM parameter store, provide the SSM parameter name in the format AWS'{{resolve:ssm:[a-zA-Z0-9_.-/]+:\d+}}'.

If you use a custom AMI, ensure that it meets the following requirements:

  • EC2 instance metadata service (with either version V2 or V1) must be activated.
  • The latest version of AWS Systems Manager Agent (SSM) must be installed.
  • If the custom AMI has a Windows operating system, AWS Tools for PowerShell must be installed.

EC2 Instance Keypair Name

Required

Choose an EC2 keypair name to allow remote access to EC2 instances.

Elastic IP Address Allocation ID

Optional

Provide the Allocation ID of an elastic IP address in this format, eipalloc-XXXXXXXX.

You may need an elastic IP address if you want to map the site domain name to the elastic IP address and access the EC2 instance via RDP/SSH from outside of the AWS environment.

Leave this parameter empty if you don't want to assign an elastic IP address to the EC2 instance.

Amazon VPC Configuration

Parameter nameRequired?Parameter description

VPC ID

Required

Choose a VPC ID.

Note:

All ArcGIS Enterprise components that are part of the same deployment must be deployed in the same VPC.

If you need to create a VPC, you can use one of the VPC sample templates: VPC with public subnets or VPC with public and private subnets and a NAT Gateway.

Subnet ID 1

Required

Choose a subnet ID. The subnet ID that you select must be within the VPC you have selected above.

If you used an Esri CloudFormation template to create the VPC, you can get the subnet ID from that template's output parameters.

Subnet ID 2

Required

Choose a second subnet ID. This must be a different subnet ID than you used for Subnet ID 1. The subnet ID that you select must be within the VPC you specified for this deployment.

If you used an Esri CloudFormation template to create the VPC, you can get the subnet ID from that template's output parameters.

Domain Name System (DNS) Configuration

Parameter nameRequired?Parameter description

ArcGIS GeoEvent Server Site Domain Name

Required

Provide the fully qualified domain name for the ArcGIS GeoEvent Server site. The domain name must exist and be resolvable. Contact your IT administrator if you are not sure of the domain name to use.

ArcGIS GeoEvent Server Configuration

Parameter nameRequired?Parameter description

EC2 Instance Type

Required

Choose an EC2 instance type. The default is m5.2xlarge.

This is the instance type that will be used for the ArcGIS GeoEvent Server machine.

This EC2 instance will be configured with the AWS Auto Recovery feature.

EC2 Instance Root Drive Disk Space

Required

The is the size of the root drive disk space for the ArcGIS GeoEvent Server EC2 instance.

Provide the size of the root drive in GB. The default is 100 GB. Minimum is 100 GB. Maximum is 1024 GB.

Deployment Bucket Name

Required

Provide the name of the Amazon S3 bucket that contains your software license files and SSL certificates. This bucket must already exist and contain the license file and SSL certificate for your deployment.

You must be the owner of the bucket and it must reside in the same AWS account as your deployment.

License File Name

Required

Provide the ArcGIS GeoEvent Server authorization file object key name. You must upload the license file (.ecp or .prvc file) to the deployment bucket before launching this stack.

To get the file object key name, browse to the file in the deployment bucket in the Amazon S3 console, for example, geoevent.prvc or resources/licenses/109/server/geoevent.prvc.

License file names are case sensitive. Ensure that you type the name correctly.

Site Administrator User Name

Required

Provide a user name for the primary site administrator for the ArcGIS GeoEvent Server site.

The name must be 6 or more alphanumeric or underscore (_) characters and must start with a letter.

Site Administrator User Password

Required

Provide a password for the primary site administrator for the ArcGIS GeoEvent Server site. You can type either a plain text password or the ARN of your secret ID from AWS Secrets Manager.

Windows arcgis user password

Conditional

Provide a password for the arcgis user. This password is only required if you deploy on Windows.

You can either enter a plain text password or the ARN of your secret ID from AWS Secrets Manager.

It's a best practice to manage your passwords in AWS Secrets Manager. For information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS.

Web Adaptor Name

Optional

To use ArcGIS Web Adaptor with the ArcGIS GeoEvent Server site, type a web adaptor name. Access to the ArcGIS GeoEvent Server site is through a URL in the format https://<fully qualified domain name>/<web adaptor name>. The name must begin with a letter and contain only alphanumeric characters.

Leave this parameter value empty if you do not want to use ArcGIS Web Adaptor, and URLs for the site will be in the format https://<fully qualified domain name><PortNumber>/arcgis.

SSL Certificate File Name

Optional

If you include a web adaptor with the site, you can provide an SSL certificate from a certifying authority (.pfx file). If you do provide a certificate, you must upload it to the deployment bucket before launching this stack.

You can get the file object key name by browsing to the file within the deployment bucket in the AWS S3 console. Examples of certificate names include domainname.pfx for a certificate file stored at the root level of the deployment bucket, or resources/sslcerts/domainname.pfx for a certificate file stored in a folder in the deployment bucket.

If you use a web adaptor and leave this parameter value empty, an autogenerated self-signed certificate will be used with the web adaptor.

SSL Certificate Password

Conditional

Provide a password for the SSL certificate. You can either type a plain text password or the ARN of your secret ID from AWS Secrets Manager. For information on creating an Amazon Resource Name for passwords, see AWS CloudFormation and ArcGIS.

Outputs

When your stack is created successfully, you can see the following output parameters on the Outputs tab of the CloudFormation stack in AWS Management Console.

Output nameOutput description

DeploymentLogsURL

This is the URL for the Amazon CloudWatch logs where all deployment logs are stored. You can refer to these logs for troubleshooting purposes if your deployment fails.

GeoEventManagerURL

The ArcGIS GeoEvent Server Manager URL

ServerManagerDirURL

The ArcGIS Server Manager URL.

ServerRestDirURL

The ArcGIS Server REST Services URL.

ServerServicesURL

The ArcGIS GeoEvent Server services URL.

You can use this URL as an input parameter in the federate server template.

StopStackFunctionName

This is the Stop Stack Lambda function URL. You can use this lambda function to stop all EC2 instances in the stack.

StartStackFunctionName

This is the Start Stack Lambda function URL. You can use this lambda function to start all EC2 instances in the stack that you previously stopped.

Considerations

The following are important points to consider after creating a CloudFormation stack containing ArcGIS deployments:

  • Do not delete any AWS resource created by this CloudFormation template. If you want to know what AWS resources have been created by this template, refer to the Resources tab of this stack in the AWS Management Console. Each resource created by an Esri CloudFormation template also has metadata tags. However, some of the resources do not show tags in the AWS Management Console.
  • You can use the AWS Lambda functions that appear in your stack outputs (listed in the Outputs section of this page) to stop EC2 instances in this stack when they are not in use and start them again when required. These functions are useful to help you manage costs.

    When you run the Lambda function to stop the EC2 instances in the deployment, the function returns a message that the instances are stopped. However, if the instances participate in an Auto Scaling group, the function must also detach the instances from the group. This can take up to 10 minutes to complete. Therefore, wait at least 10 minutes before you run the Lambda start function to restart the deployment.

Troubleshooting

If you observe any failures when creating this CloudFormation stack, see Troubleshoot ArcGIS deployments on AWS.