--- title: Step 1. Prepare your server description: To install AM in a demo or test environment, perform the following prerequisite tasks: component: pingam version: 7.3 page_id: pingam:eval-guide:step-1-prepare-server canonical_url: https://docs.pingidentity.com/pingam/8.1/evaluation/step-1-prepare-server.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Evaluation", "Install"] section_ids: prepare-fqdn: Prepare a fully qualified domain name install-jdk-and-apache-tomcat: Install a JDK and Apache Tomcat --- # Step 1. Prepare your server To install AM in a demo or test environment, perform the following prerequisite tasks: * Check disk space AM's distribution `.war` file includes an embedded DS server, which stores AM's configuration data and serves as an identity store. The DS server requires free disk space equal to or greater than 5 GB, plus 5% of the total size of the filesystem in the $HOME directory of the user running the container. * Prepare a fully qualified domain name (FQDN) AM requires that you use fully qualified domain names. This is because AM uses HTTP cookies to keep track of sessions for single sign-on (SSO), and setting and reading cookies depends on the server name and domain. For information on preparing an FQDN, see [Prepare a fully qualified domain name](#prepare-fqdn). * Install a supported Java development kit (JDK) AM is a Java web application, so you need to download and install a supported JDK. For the list of supported JDK versions, refer to the [Java requirements](https://docs.pingidentity.com/pingam/release-notes/requirements.html#prerequisites-java). For information on installing a JDK, see [Install a JDK and Apache Tomcat](#install-jdk-and-apache-tomcat). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Ensure that the JDK's default truststore, for example, `$JAVA_HOME/lib/security/cacerts`, has, at least, `644` permissions:```bash $ sudo chmod 644 $JAVA_HOME/lib/security/cacerts ``` | > **Collapse: Why is this required?** > > When evaluating AM, the installation process deploys an embedded DS instance that AM uses as configuration store, user store, and [CTS store](../cts-guide/preface.html). To connect to the DS instance using LDAPS, AM requires access to the self-signed certificate that DS generates. > > If you are [installing AM for evaluation purposes](preface.html), AM creates a copy of your JDK's default `lib/security/cacerts` truststore, names it `truststore`, and places it in `/path/to/openam/security/keystores/`. > > AM then attempts to add the DS self-signed certificate to that store, with an alias of `ds-ca-cert`. > > | | | > | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | | If the `lib/security/cacerts` truststore does not have the default password of `changeit`, and/or if it does not have at least `644` permissions, then AM installation will fail, as it will not be able to open the truststore to add the DS certificate. | You can change the permissions back as they were originally after installing AM. * Install a supported web container Although AM can run in a number of application servers, download [Apache Tomcat](http://tomcat.apache.org/) for now. For the list of supported versions, refer to [Application containers](https://docs.pingidentity.com/pingam/release-notes/requirements.html#prerequisites-application-servers). For information on installing Apache Tomcat, see [Install a JDK and Apache Tomcat](#install-jdk-and-apache-tomcat). * Download ForgeRock Access Management The [Ping Identity Download Center](https://backstage.pingidentity.com/downloads) hosts downloadable versions of AM. For the list of supported operating systems, refer to the [Operating system requirements](https://docs.pingidentity.com/pingam/release-notes/requirements.html#operating-systems). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The procedures to set up the software are written for use on a UNIX-like system.If you are running Microsoft Windows, adapt these examples accordingly. | ## Prepare a fully qualified domain name Before deploying and installing AM, give your system a DNS alias, such as `openam.example.com`. You can add a DNS alias by editing your [hosts file](http://en.wikipedia.org/wiki/Hosts_\(file\)). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you already have a DNS server set up, or use a service such as [localtest.me](https://readme.localtest.me/), you can use those instead of editing your hosts file. | 1. Add the aliases to your hosts file using your preferred text editor: ```bash # Edit /etc/hosts $ sudo vi /etc/hosts Password: $ cat /etc/hosts | grep openam 127.0.0.1 localhost openam.example.com ``` 2. Proceed to [install a JDK and Apache Tomcat](#install-jdk-and-apache-tomcat). ## Install a JDK and Apache Tomcat AM runs as a Java web application inside an application container. Apache Tomcat is an application container that runs on a variety of platforms. The following instructions are loosely based on the `RUNNING.txt` file delivered with Apache Tomcat: 1. Extract the JDK download file: ```bash $ mkdir -p /path/to/JDK $ unzip ~/Downloads/openjdk-X_bin.zip -d /path/to/JDK ``` 2. Extract the Apache Tomcat download file: ```bash $ mkdir -p /path/to/tomcat $ unzip ~/Downloads/apache-tomcat-X.X.XX.zip -d /path/to/tomcat ``` 3. Create an Apache Tomcat script to set the `JAVA_HOME` environment variable to the file system location of the JDK and to set the heap and metaspace size appropriately. For example: * Unix/Linux * Windows Create a `setenv.sh` script in `/path/to/tomcat/bin/`: ```bash export JAVA_HOME="/path/to/usr/jdk" export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxMetaspaceSize=256m" ``` Create a `setenv.bat` script in `\path\to\tomcat\bin\`: ```powershell PS C:\path\to> $env:JAVA_HOME += ";C:\path\to\usr\jdk" PS C:\path\to> $env:CATALINA_OPTS += ";-Xmx2g -XX:MaxMetaspaceSize=256m" ``` 4. (UNIX-like systems only) Make the scripts in Apache Tomcat's `bin/` directory executable: ```bash $ chmod +x /path/to/tomcat/bin/*.sh ``` 5. If you have a custom installation that differs from the documented Apache Tomcat installation, make sure to set Apache Tomcat's `CATALINA_TMPDIR` to a writable directory to ensure the installation succeeds. This temporary directory is used by the JVM (`java.io.tmpdir`) to write disk-based storage policies and other temporary files. 6. Make sure that your system's firewall does not block the port that Apache Tomcat uses (`8080` by default). See the Apache documentation for instructions for allowing traffic through the firewall on a specific port for the version of Apache Tomcat on your system. A variety of firewalls are in use on Linux systems. The version your system uses depends on your specific distribution. 7. Start Apache Tomcat: ```bash $ /path/to/tomcat/bin/startup.sh ``` It might take Apache Tomcat several seconds to start. When it has successfully started, you should see information indicating how long startup took in the `/path/to/tomcat/logs/catalina.out` log file. ``` INFO: Server startup in 4655 ms ``` 8. Go to Apache Tomcat's homepage; for example, `http://openam.example.com:8080`. If Apache Tomcat works correctly, the homepage displays a success message: "If you're seeing this, you've successfully installed Tomcat. Congratulations!". 9. Proceed to [Step 2. Deploy AM](step-2-deploy-am.html).