> For the complete documentation index, see [llms.txt](https://docs.servoy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.servoy.com/reference/servoy-cloud/on-premise-deployment.md). # On-Premise Deployment Deploy a Servoy Cloud application on your own infrastructure with Docker, including configuration parameters, environment variables, and Satellite setup. {% hint style="info" %} What was previously called "Remote (On-Premise)" is now called **Satellite** as of the 2026.03 release. This is a label-only change — no configuration or behavior has changed. {% endhint %} ## When to use Satellite deployment Satellite deployment was previously called Remote (On-Premise). A Satellite deployment makes sense when your data or infrastructure requirements mean you cannot run in the cloud, for example due to data residency regulations, network restrictions, or existing on-premise infrastructure investments. Your application runs on your own servers. You build and package it in Servoy Cloud, then run that image on your own infrastructure. You can also connect it back to the Cloud Control Center for log and metric monitoring, but that connection is optional. ## Docker deployment ### 1. CCC Configuration Parameters {% hint style="warning" %} Configure Docker pull commands by using your namespace-related parameters. Look for placeholders in the commands marked as **`${parameter-name}`** and replace them with the corresponding values {% endhint %} #### Command parameters Command parameters are accessible via the Docker Information dialog within the Cloud Control Center. You can access this dialog from the following locations: * Current Package context menu in the Pipelines view * Artifacts tab in the Package Details #### Parameter names: * namespace-name * region-name * docker-repo-name #### AWS Parameters Access AWS parameters through the [Credentials](/reference/servoy-cloud/cloud-control-center/administration/credentials.md#overview) menu in the Cloud Control Center, including: * AWS Access Key ID * AWS Secret Access Key #### Remote Environment Token Your image ships with a Remote Environment token, so logs and performance metrics flow to the Cloud Control Center out of the box. You don't set this token yourself. On startup the environment uses the token to call Servoy Cloud and pull back the connection settings for log and metric shipping. To opt out, override the token with an empty value, for example `-e "REMOTE_ENVIRONMENT_TOKEN="`. The application runs the same either way. Opting out only means no logs or metrics are sent. You can find the token for your environment in the [Credentials](/reference/servoy-cloud/cloud-control-center/administration/credentials.md#overview) menu in the Cloud Control Center. ### 2. Pre-requisites * Docker * AWS CLI ### 3. Install requirements {% tabs %} {% tab title="Linux" %} #### Installation Commands {% code overflow="wrap" fullWidth="true" %} ```bash curl "https://amazon-ecr-credential-helper-releases.s3.us-east-2.amazonaws.com/0.5.0/linux-amd64/docker-credential-ecr-login" -o docker-credential-ecr-login chmod +x docker-credential-ecr-login sudo mv docker-credential-ecr-login /usr/local/bin/ curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" unzip awscliv2.zip sudo ./aws/install aws configure ``` {% endcode %} {% endtab %} {% tab title="Mac" %} #### Installation Commands ```bash brew install docker-credential-helper-ecr curl https://awscli.amazonaws.com/AWSCLIV2.pkg -o AWSCLIV2.pkg sudo installer -pkg AWSCLIV2.pkg -target / aws configure ``` {% endtab %} {% tab title="Windows" %} #### Guides for Installation [Guide to install aws-cli v2 on Windows](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-windows.html)\ [Guide to install and configure Docker on Windows](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-docker/configure-docker-daemon) #### Installation steps 1\. [Download aws-cli v2
](https://awscli.amazonaws.com/AWSCLIV2.msi) 2\. [Download docker credential helper](https://amazon-ecr-credential-helper-releases.s3.us-east-2.amazonaws.com/0.5.0/windows-amd64/docker-credential-ecr-login.exe) and add it as a Windows PATH variable\ 3\. Open **CMD** and run: ```bash aws configure ``` {% endtab %} {% endtabs %} ### 4. Configuration settings #### Linux and Mac ```bash vi ~/.docker/config.json ``` #### Windows ```bash code .docker/config.json ``` #### General Edit the `config.json` file, adding other configuration settings: ```json { #OTHER CONFIG SETTINGS "credHelpers": { "428597928572.dkr.ecr.${region-name}.amazonaws.com": "ecr-login" } } ``` ### 5. Pull docker image To pull the Docker image, execute the following commands: {% tabs %} {% tab title="Linux and Mac" %} **For Authentication** Generate a login password for Amazon ECR: 
aws ecr --region ${region-name} get-login-password | docker login --password-stdin --username AWS 428597928572.dkr.ecr.${region-name}.amazonaws.com
**Pull Command** Fetch the specific Docker image using: 
docker pull 428597928572.dkr.ecr.${region-name}.amazonaws.com/${namespace-name}/${docker-repo-name}:latest
{% endtab %} {% tab title="Windows" %} **Pull Command** Fetch the specific Docker image using: 
docker pull 428597928572.dkr.ecr.${region-name}.amazonaws.com/${namespace-name}/${docker-repo-name}:latest
{% endtab %} {% endtabs %} ### 6. Running the docker image To run the docker image the basic call is: ```bash docker run -d --name servoy -p 8080:8080 -e "DB_POSTGRES_PASSWORD=${MY_POSTGRES_PASSWORD}" -e "DB_POSTGRES_SERVER=${MY_POSTGRES_URL}" -e "DB_POSTGRES_PORT=5432" -v "${PATH_TO_STORE_SERVOY_FILES}:/usr/local/servoy" 428597928572.dkr.ecr.${region-name}.amazonaws.com/${namespace-name}/${docker-repo-name}:latest ``` The image runs in Satellite mode by default. You can set `-e "ENVIRONMENT=onprem"` explicitly, but it is optional. {% hint style="info" %} Your image ships with a Remote Environment token, so it reports logs and metrics to the Cloud Control Center out of the box. To opt out, override the token with an empty value:\ -e "REMOTE\_ENVIRONMENT\_TOKEN="\ The application runs the same either way. Opting out only means no logs or metrics are sent to Servoy Cloud. {% endhint %} #### How the environment is identified in Servoy Cloud Each Satellite environment reports a hostname to Servoy Cloud so it can be counted as a distinct deployment. The hostname is built automatically from the build information and the container host, so you don't set it yourself. You see this derived name in the Cloud Control Center once the environment reports in with its Remote Environment token. In this sample it is running connected to a postgres server, the following `-e` options can be used when you are starting your docker container: | Docker Env Property | Default value | Description | | -------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | TOMCAT\_USERNAME | admin | Tomcat username | | TOMCAT\_PASSWORD | Test123456789 | Tomcat Password | | JAVA\_XMS | 256m | Java min memory setting for tomcat | | JAVA\_XMX | 3g | Java max memory setting for tomcat | | CERTIFICATE\_NAME | | Certificate file name to use tomcat with SSL | | CERTIFICATE\_PASS | | Certificate file password to load the certificate file | | DB\_POSTGRES\_SERVER | dev-postgresql-service | Postgres Server URL | | DB\_POSTGRES\_USERNAME | postgres | Postgres Username | | DB\_POSTGRES\_PASSWORD | | Postgres Password | | DB\_POSTGRES\_PORT | 5432 | Postgres Port | | DB\_MSSQL\_SERVER | dev-mssql-service | MSSQL Server URL | | DB\_MSSQL\_USERNAME | sa | MSSQL Username | | DB\_MSSQL\_PASSWORD | | MSSQL Password | | DB\_MSSQL\_PORT | 1433 | MSSQL Port | | DB\_MYSQL\_SERVER | dev-mysql-service | MYSQL Server URL | | DB\_MYSQL\_USERNAME | root | MYSQL Username | | DB\_MYSQL\_PASSWORD | | MYSQL Password | | DB\_MYSQL\_PORT | 3306 | MYSQL Port | | SERVOY\_TESTING\_MODE | false | Property to enable servoy E2E testing | | REMOTE\_ENVIRONMENT\_TOKEN | Set by the build | Ships with your image to send logs and metrics to the Cloud Control Center. Set an empty value to opt out of reporting. Found in the Credentials menu in CCC | | TIMEZONE | Etc/UTC | Set the timezone of the Servoy Application Server | #### Enabling SSL with a certificate To run Tomcat with SSL, set `CERTIFICATE_NAME` and `CERTIFICATE_PASS`, then mount the folder that holds your certificate file so the container can read it. Add this volume mapping to your `docker run` command: ```bash -v ${MY_CERTS}:/usr/local/servoy-certificate ``` {% hint style="info" %} Without this volume, Tomcat can't find the certificate file named in `CERTIFICATE_NAME` and SSL won't start. {% endhint %} ### 7. Verify the environment After the container starts, confirm it is running and reachable. Check that the container is up: ```bash docker ps --filter "name=servoy" ``` Follow the startup logs and watch for Tomcat finishing deployment: ```bash docker logs -f servoy ``` Then open `http://localhost:8080` in a browser. You should reach your application. If you left the Remote Environment token in place, the environment reports to the Cloud Control Center on startup. Open the Cloud Control Center and confirm the Satellite environment shows up with its auto-derived hostname. If it doesn't appear, check the container logs for a line starting with `ERROR -start-environment`, which points to a token or connectivity problem. [^1]: Replace with the region-name value provided in the CCC Docker Information dialog. [^2]: Replace with the namespace-name value provided in the CCC Docker Information dialog. [^3]: Replace with the docker-repo-name value provided in the CCC Docker Information dialog. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.servoy.com/reference/servoy-cloud/on-premise-deployment.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.