> ## Documentation Index
> Fetch the complete documentation index at: https://docs.symmetry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Deploy SPF on-premise

> Install and verify SPF On-Premise in your servlet container. Covers `SPF_HOME` setup, `settings.json`, SSL and cookies, logging, and first deployment checks.

Symmetry Payroll Forms (SPF) On-Premise runs as a Java web application (`spf.war`) that you deploy in your own servlet container, such as Tomcat. You control the server, and you're responsible for installation, deployment, and maintenance. This guide walks a new on-premise client through downloading the application, deploying it, configuring `settings.json`, and verifying a live installation.

For a comparison of API, Hosted, and On-Premise delivery, see [Implementation types](/spf/overview/implementation-types).

## Before you begin

You'll need login credentials for the [Download Center](https://client-downloads.symmetry.com/) to complete this guide. If you don't have them, contact your Symmetry Account Manager or reach out through the [Client Support Center](https://support.symmetry.com).

Confirm your server meets the minimum specifications before you start:

* Java 8+
* A Servlet 3.1+ container, such as Tomcat 8.5+, Jetty 9.4+, or WildFly 10+
* 4GB of memory and 1GB of disk space (SPF + Tomcat + Java + space for logs)
* Courier, Courier-Bold, and ZapfDingbats fonts (or an appropriate substitute) installed on the server

See [Updating Symmetry Payroll Forms](/spf/on-premise/updating#minimum-specifications) for the full list of minimum and suggested system requirements, including font substitutes.

<CardGroup cols={2}>
  <Card title="On-Premise Settings" icon="sliders" href="/spf/on-premise/settings">
    Full reference for every element in your `settings.json` file.
  </Card>

  <Card title="Settings Builder" icon="wrench" href="/spf/hosted-and-on-premise/settings-builder">
    Prototype and troubleshoot your SPF Registration without touching your own application.
  </Card>
</CardGroup>

***

## Step 1: Download the installation files

Log into the [Download Center](https://client-downloads.symmetry.com/) and download the following:

| File                   | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `spf.war`              | The SPF web application                                                               |
| `SPF_HOME example.zip` | Supplemental files, including the default [`settings.json`](/spf/on-premise/settings) |

## Step 2: Set up `SPF_HOME`

<Steps>
  <Step title="Unzip and rename">
    Unzip `SPF_HOME example.zip` and rename the folder from `SPF_HOME example` to `SPF_HOME`. Copy it to your chosen installation directory. Inside, you'll find one subfolder, `app-data`, used for storing application settings and multistate library configuration files.
  </Step>

  <Step title="Set the system environment variable">
    Create a system environment variable named `SPF_HOME` and set its value to the path of the `SPF_HOME` folder.

    ```ini theme={null}
    # Example on Windows
    SPF_HOME = C:/SPF_HOME
    ```
  </Step>

  <Step title="Set folder permissions">
    The application requires read/write access to all folders and subfolders within `SPF_HOME`.
  </Step>
</Steps>

## Step 3: Deploy the application

<Steps>
  <Step title="Place `spf.war` in your servlet container">
    Copy `spf.war` into the webapps folder of your servlet container.

    ```text theme={null}
    # Example: Tomcat 8 on Windows
    C:\apache\tomcat8\webapps\spf.war
    ```

    <Warning>
      Do not rename `spf.war`. The application has internal dependencies that rely on this exact filename.
    </Warning>
  </Step>

  <Step title="Set minimum memory">
    Set the maximum available memory for your Java servlet container/JVM to at least **4GB**. Symmetry suggests **16GB** for production environments.
  </Step>

  <Step title="Start your servlet container">
    Start (or restart) your servlet container to deploy the application.
  </Step>
</Steps>

<Tip>
  Using Tomcat 10? You'll need an extra step, since Tomcat 10 switched to the Jakarta servlet implementation, which is incompatible with SPF. See [Using Tomcat](/spf/on-premise/updating#using-tomcat) for the workaround.
</Tip>

## Step 4: Configure `settings.json`

The `settings.json` file in your `SPF_HOME` directory controls SPF's behavior: form modes, postback, address normalization, presentation, and more. Settings apply to all sessions after the application initializes, and Symmetry provides a default file in `SPF_HOME example.zip`.

At minimum, review and configure:

* `config.formSubmissionMode`: set to `"POSTBACK"` or `"PRINT"`
* `config.postback.target.url`: required if `formSubmissionMode` is `"POSTBACK"`; the endpoint where SPF sends the completed form data
* `config.webservice.apiKey`: your Symmetry-provided API key for the [Symmetry Location Service (SLS)](/spf/on-premise/symmetry-location-service)
* `config.webservice.enabled`: set to `true` to enable address normalization and geocoding

See [On-Premise Settings](/spf/on-premise/settings) for the full reference of available elements, and the [SPF Schema & Complete List of SPF Elements](/spf/references/schema-and-elements) for every element available in the SPF Registration itself.

<Info>
  Any setting defined in `settings.json` can be overridden per session by passing the same JSON element with a different value in the SPF Registration.
</Info>

## Step 5: Configure SSL and cookies

If you are terminating SSL at a load balancer or proxy, or embedding SPF in an iframe, you'll need additional server configuration before going live.

<CardGroup cols={2}>
  <Card title="SameSite cookies" icon="cookie" href="/spf/on-premise/configuration#samesite-cookies">
    Required if embedding SPF in an iframe. Configure your servlet container to use secure, HTTP-only cookies.
  </Card>

  <Card title="SSL/TLS termination" icon="shield" href="/spf/on-premise/configuration#ssl-tls-termination">
    Required if decrypting HTTPS at the load balancer level. Configure x-forwarded-\* headers.
  </Card>
</CardGroup>

<Warning>
  SPF does not recommend using iframes due to third-party cookie restrictions in Safari, iOS, and Chrome. See [Third-party cookie restrictions and iframes](/spf/on-premise/configuration#third-party-cookie-restrictions-and-iframes) before proceeding with an iframe implementation.
</Warning>

## Step 6: Verify the installation

Once your server is running, test the installation by navigating to:

```text theme={null}
/spf/do-test
```

Select **Test web service** on the test page. A successful result confirms that the `SPF_HOME` environment variable is set, `spf.war` is found, and the application has read/write permissions.

Once the test page passes, verify the full registration flow using [Settings Builder](/spf/hosted-and-on-premise/settings-builder) at:

```text theme={null}
https://[yourservername]:[yourserverport]/spf/utility/settings-builder
```

Settings Builder lets you generate a prototype SPF Registration, submit it to SPF, and receive a real Postback response, without needing to build your own integration first.

## Step 7: Set up logging (optional)

SPF can write transaction logs to a directory of your choice. To enable logging, create a system environment variable named `SPF_LOG_LOCATION` and set its value to your desired log directory.

```ini theme={null}
# Example
SPF_LOG_LOCATION = C:\SPF_HOME\logs
```

See [Logging](/spf/on-premise/logging) for full setup instructions, log naming conventions, and retention configuration.

## Next steps

<CardGroup cols={2}>
  <Card title="On-premise settings" icon="sliders" href="/spf/on-premise/settings">
    Full reference for every `settings.json` element.
  </Card>

  <Card title="Core concepts overview" icon="lightbulb" href="/spf/core-concepts/overview">
    The model behind every SPF integration: forms, determination, and outputs.
  </Card>
</CardGroup>

More references:

* [SPF on-premise configuration](/spf/on-premise/configuration)
* [SPF on-premise logging](/spf/on-premise/logging)
* [Updating Symmetry Payroll Forms](/spf/on-premise/updating)
* [SPF registration](/spf/hosted-and-on-premise/registration)
* [Settings builder](/spf/hosted-and-on-premise/settings-builder)
* [Helper pages](/spf/hosted-and-on-premise/helper-pages)