> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart: Deploy Your First App
> Put your first app online on Square Cloud in minutes: write a small web server, add the configuration file, zip it and deploy from the dashboard or the CLI.
This guide deploys a small Node.js web server so you can see the whole flow end to end: three files, one zip and one upload. The steps are the same for a bot or for another language.
## Before you begin
Square Cloud is a paid platform: an active plan is required to deploy, so your project runs on production-grade infrastructure from day one. Create your account, then [select the plan](https://squarecloud.app/en/pricing) that's right for you (see [what each plan includes](/en/platform/plans)).
If you've never used Square before, sign up to get started.
If you already have an account, log in to get started.
## Create the project
Create a folder with these three files.
`index.js` answers every request with a short message. It reads the port and host from the `PORT` and `HOST` environment variables, which Square Cloud sets to `80` and `0.0.0.0`:
```javascript index.js theme={"system"}
const http = require("node:http");
const port = process.env.PORT || 3000;
const host = process.env.HOST || "0.0.0.0";
http
.createServer((req, res) => {
res.writeHead(200, { "Content-Type": "text/plain" });
res.end("Hello from Square Cloud!");
})
.listen(port, host, () => {
console.log(`Listening on http://${host}:${port}`);
});
```
Every Node.js project needs a `package.json`: Square Cloud installs the packages it lists before starting your app. This example has none, but the file must exist and can't be empty.
```json package.json theme={"system"}
{
"name": "hello-square",
"version": "1.0.0",
"private": true,
"main": "index.js",
"scripts": {
"start": "node index.js"
}
}
```
`squarecloud.app` tells Square Cloud which file to run, how much memory to reserve and which runtime version to use. `SUBDOMAIN` publishes the app as a website at `https://.squareweb.app`, so pick a name nobody has taken yet.
```systemd squarecloud.app theme={"system"}
MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Hello Square
SUBDOMAIN=hello-square-yourname
```
Every field is explained in the [configuration file reference](/en/getting-started/config-file). The [VS Code extension](/en/vscode-extension/features#config-file-intellisense) autocompletes and checks this file as you type.
A website must listen on port **80** and host **0.0.0.0**. A server bound to `localhost`, `127.0.0.1` or another port (such as 3000 or 8080) can't be reached, and the site shows a timeout page. Reading `PORT` and `HOST`, as `index.js` does, gets this right on Square Cloud and still runs on port 3000 on your machine.
Deploying a bot instead? Leave out `SUBDOMAIN`, add `AUTORESTART=true`, and keep the token in an [environment variable](/en/platform/environment-variables), never in the code. The [Discord bot tutorial](/en/tutorials/bots/discord) walks through a complete bot.
## Zip the project
Deploying with the CLI? Skip this section: `squarecloud upload` zips the folder for you.
Open the project folder and select everything inside it. `squarecloud.app` must sit at the top level of the zip: if you compress the folder itself, the files end up inside a subfolder and the deploy fails with `MISSING_CONFIG`.
Right-click the selected files and choose **Compress to ZIP file** (Windows 11) or **Send to** → **Compressed (zipped) folder**.
Control-click the selected files and choose **Compress**.
Right-click the selected files and choose **Compress**, or run `zip -r ../app.zip .` inside the folder.
The zip can be up to **100 MB**. Leave out `node_modules`, virtual environments and build caches: dependencies are installed on the server, and those folders are [deleted on deploy](https://help.squarecloud.app/en-us/article/which-files-are-deleted-on-deploy-1j0krik/) anyway.
## Deploy
Upload the zip in the dashboard, or deploy with one command from the CLI.
### Via dashboard
Access the [upload page](https://squarecloud.app/en/dashboard/new) and upload your project zip file.
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.
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.
Your first deploy usually takes less than a minute. In the [dashboard](https://squarecloud.app/en/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 `https://.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.
App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes.
### Via CLI
To use this method, your project needs a configuration file named `squarecloud.app` at its root. It tells Square Cloud how to run your application.
Learn how to create the `squarecloud.app` configuration file that defines your application's environment.
Install the [Square Cloud CLI](/en/cli-reference/installation). If you already have it, run the same command to update it:
```bash macOS, Linux, and WSL theme={"system"}
curl -fsSL https://cli.squarecloud.app/install | bash
```
```bash Windows with npm theme={"system"}
npm install -g @squarecloud/cli@latest
```
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](/en/cli-reference/authentication).
```bash theme={"system"}
squarecloud auth login
```
From your project folder, run the command below. The CLI zips the current folder, leaving out what [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) lists, and uploads it:
```bash theme={"system"}
squarecloud upload
```
To upload a zip you created yourself, pass it with `--file`:
```bash theme={"system"}
squarecloud upload --file
```
Your first deploy usually takes less than a minute. Check your application status and logs directly from the terminal:
```bash theme={"system"}
squarecloud app status
squarecloud app logs
```
If you deployed a website or API, open `https://.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.
App not starting? See the [Troubleshooting guide](/en/platform/troubleshooting/app-wont-start) for the most common causes and fixes.
Once the app is running, `https://hello-square-yourname.squareweb.app` (with your subdomain) answers `Hello from Square Cloud!`.
Want a deploy on every push? [Connect a GitHub repository](https://help.squarecloud.app/en-us/article/how-to-connect-your-github-repository-and-deploy-automatically-mr6srt/) or use the [GitHub Actions workflow](https://help.squarecloud.app/en-us/article/workflow-github-actions-automated-deploy-ff34mk/).
## Next steps
Every `squarecloud.app` field: memory, start command, subdomain and automatic restarts.
Store tokens and connection strings outside your code.
Fix upload errors, sites that don't load and apps that won't start.
Upload, commit and follow logs without leaving your editor.
### Guides for your language
Each guide covers the dependency file, the start command and the common pitfalls of its runtime.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.