Introduction
To develop and host an Uptime Kuma instance on Square Cloud, it’s essential to follow a structured sequence of configurations and prerequisites. This technical guide will cover the entire process, from initial setup to production deployment.Prerequisites
- Square Cloud Account: Register through the signup page using your email.
- Active plan: Ensures dedicated resources and optimized performance for your application. Check our available plans and choose the most suitable for your needs.
Get the project
Choose a version in our uptimekuma-web releases and download itsproject.zip.
Configure Square Cloud
The project already includes its configuration file,squarecloud.config. If you want a custom subdomain instead of a random hash, set the desired subdomain in it:
squarecloud.config
You can also set this through the upload menu.
PORT and HOST environment variables, which Square Cloud sets to 80 and 0.0.0.0.
What goes in the ZIP
Upload theproject.zip with all its files. If you extract it to edit squarecloud.config, compress the contents again so that squarecloud.config stays at the root of the ZIP, next to package.json.
Deploy and verify
Via dashboard
1
Access the Upload Page
Access the upload page and upload your project zip file.
2
Configure Your Environment
After uploading your zip, you will need to configure the name, main file or runtime environment and other settings for your project.
If you are uploading a web project, make sure to select “Web Publication” and set a subdomain to your project.
If you are uploading a web project, make sure to select “Web Publication” and set a subdomain to your project.
3
Deploy Your Project
Finally, click on the “Deploy” button to host your project on Square Cloud.
After deployment, you can monitor your project’s status and logs from the dashboard.
After deployment, you can monitor your project’s status and logs from the dashboard.
4
Confirm Your App Is Live
Your first deploy usually takes less than a minute. In the dashboard, wait for your application status to show as running and check the logs for any startup errors.
If you deployed a website or API, open
If you deployed a website or API, open
https://<your-subdomain>.squareweb.app in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.
Via CLI
To use this method, your project needs a configuration file namedsquarecloud.app at its root. It tells Square Cloud how to run your application.
Configuration file guide
Learn how to create the
squarecloud.app configuration file that defines your application’s environment.1
Install the CLI
Install the Square Cloud CLI. If you already have it, run the same command to update it:
2
Log In
Run the command below. It opens your browser: approve the login there and the CLI is ready. There is no API key to copy. For scripts and CI, see CLI authentication.
3
Upload Your Project
From your project folder, run the command below. The CLI zips the current folder, leaving out what To upload a zip you created yourself, pass it with
squarecloud.ignore lists, and uploads it:--file:4
Confirm Your App Is Live
Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal:If you deployed a website or API, open
https://<your-subdomain>.squareweb.app in your browser: you should see your application responding. If you deployed a bot, send it a command to confirm it is online.
First access
Right after the deploy, openhttps://my-uptime-kuma.squareweb.app and create the admin account. Whoever opens the page first creates it, so do it before sharing the URL with anyone.
Common errors
Custom domain
To use a custom domain (e.g.,
mysite.com) instead of the default URL mysite.squareweb.app, you need the Standard plan or higher. The default URL comes from the SUBDOMAIN field in the configuration file. To connect your domain, follow how to set up your own domain.Minimum RAM requirements
Minimum: 512MB RAM for websites and APIs, enough for a static build on the static runtime. For apps that render pages on a server (Next.js, Nuxt, Angular SSR and similar), we recommend at least 1GB RAM. For larger applications, allocate more RAM to prevent the application from running out of memory and crashing.
Could not find this site.
Check if the subdomain/domain matches what’s configured in the SUBDOMAIN field or in the custom domain settings. If you just uploaded the site, wait up to 60 seconds for Square to enable first access.
Site took too long to respond…
Your server must listen on port 80 and host 0.0.0.0. Square Cloud sets the PORT (
80) and HOST (0.0.0.0) environment variables in your application: read them in your code instead of hardcoding other values. A server that listens only on localhost or 127.0.0.1 never receives requests.Next steps
Custom domain
Serve your status pages from your own domain.
n8n
Automate what happens when a monitor goes down.
App won't start
Fix missing modules, memory errors and other startup failures.