Referenz der squarecloud.app-Konfigurationsdatei

Was ist die Konfigurationsdatei?

Die Konfigurationsdatei sagt Square Cloud, wie deine Anwendung ausgeführt wird: welche Datei startet, wie viel Arbeitsspeicher reserviert wird, welche Runtime-Version zum Einsatz kommt und, bei einer Website, welche Subdomain veröffentlicht wird. Sie ist eine einfache Textdatei mit einem KEY=VALUE-Paar pro Zeile.

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My first app

Die Konfigurationsdatei erstellen

Erstelle im Stammverzeichnis deines Projekts eine Datei namens squarecloud.app oder squarecloud.config. Beide Namen funktionieren gleich. Wenn du eine ZIP-Datei hochlädst, muss die Datei auf der obersten Ebene der ZIP-Datei liegen, nicht in einem Unterordner, sonst schlägt der Deploy mit MISSING_CONFIG fehl.

Unter macOS empfehlen wir den Namen squarecloud.config.

Die VS Code-Erweiterung vervollständigt jeden der folgenden Schlüssel und unterstreicht ungültige Werte schon beim Tippen.

Konfigurationsparameter

MEMORY, VERSION und DISPLAY_NAME sind immer Pflicht. MAIN ist Pflicht, sofern du nicht RUNTIME setzt.

Parameter	Pflicht	Nach dem Deploy änderbar	Limit	Zweck
`MAIN`	Außer wenn `RUNTIME` gesetzt ist	Nein	32 Zeichen	Datei, die die Anwendung startet.
`MEMORY`	Ja	Ja	Der freie RAM deines Plans	Für die Anwendung reservierter RAM, in MB.
`VERSION`	Ja	Nein	`recommended` oder `latest`	Runtime-Version.
`DISPLAY_NAME`	Ja	Ja	32 Zeichen	Im Dashboard angezeigter Name.
`DESCRIPTION`	Nein	Ja	280 Zeichen	Kurze Beschreibung.
`AUTORESTART`	Nein	Ja	`true` oder `false`	Die Anwendung nach einem Absturz neu starten.
`SUBDOMAIN`	Nein	Nur bei Websites	63 Zeichen	Veröffentlicht die Anwendung als Website.
`RUNTIME`	Nein	Nein	Siehe Tabelle	Runtime, wenn `MAIN` sie nicht erkennen lässt.
`START`	Nein	Ja	256 Zeichen	Eigener Startbefehl.

Änderbare Parameter kannst du nach dem Deploy im Dashboard anpassen. Um einen nicht änderbaren Parameter zu ändern, musst du die Anwendung erneut hochladen.

MAIN

Die Datei, die deine Anwendung startet, relativ zum Stammverzeichnis des Projekts.

MAIN=index.js

MAIN=src/bot/main.py

Die Dateiendung bestimmt die Runtime: .js läuft auf Node.js, .ts auf TypeScript, .py auf Python und so weiter.
Die Datei muss in deinem Upload vorhanden sein und darf nicht leer sein.
Bis zu 32 Zeichen: Buchstaben, Ziffern, _, ., / und -, keine Leerzeichen.

Fehlt MAIN (ohne RUNTIME), schlägt der Deploy mit MISSING_MAIN fehl; eine Datei, die nicht existiert, keine Endung hat oder gegen die obigen Regeln verstößt, führt zu INVALID_MAIN.

MEMORY

Der für deine Anwendung reservierte RAM in Megabyte. Er bestimmt auch die vCPUs und die Bandbreite deiner Anwendung.

MEMORY=512

Der Wert muss mindestens dem Minimum für deinen Projekttyp entsprechen und darf nicht über dem RAM liegen, den dein Plan noch frei hat. Andernfalls schlägt der Deploy mit INSUFFICIENT_MEMORY fehl.

VERSION

Die Runtime-Version: recommended oder latest. Jeder andere Wert, auch eine exakte Versionsnummer, lässt den Deploy mit INVALID_VERSION fehlschlagen.

VERSION=recommended

Verwende recommended, sofern du keine Funktion brauchst, die nur das neueste Release bietet. Welche Versionen hinter jedem Wert stehen, zeigt die Tabelle der Runtime-Versionen.

DISPLAY_NAME

Der Name, der im Dashboard, in der CLI und in der API angezeigt wird.

DISPLAY_NAME=Admin bot

Bis zu 32 Zeichen: Buchstaben ohne Akzente oder Umlaute, Ziffern, Leerzeichen, - und _. Alles andere, etwa Umlaute, akzentuierte Buchstaben oder Emojis, führt zu INVALID_DISPLAY_NAME.

DESCRIPTION

Eine kurze Beschreibung der Anwendung, bis zu 280 Zeichen (darüber hinaus INVALID_DESCRIPTION).

DESCRIPTION=This bot helps with your daily tasks.

AUTORESTART

Startet die Anwendung nach einem Absturz automatisch neu. Akzeptiert true oder false und steht standardmäßig auf false: Schalte es also für Bots und alles ein, was online bleiben muss.

AUTORESTART=true

Ein automatischer Neustart erfolgt nur, wenn alle diese Bedingungen erfüllt sind:

Die Anwendung wurde mit Status 1 beendet, dem üblichen Exit-Code eines unbehandelten Fehlers in Node.js und Python.
Sie lief mindestens 60 Sekunden, sodass eine App, die direkt beim Start abstürzt, nicht in einer Schleife neu gestartet wird.
Sie wurde in der letzten Stunde nicht automatisch neu gestartet.
Die Logs zeigen keinen Fehler, den ein Neustart nicht beheben kann: ein ungültiges Bot-Token, ein fehlendes Modul, einen Syntax- oder TypeScript-Typfehler oder eine fehlgeschlagene Installation der Abhängigkeiten.

Ein Neustart hält die App bei einem vorübergehenden Fehler online, aber der eigentliche Bug muss trotzdem in deinem Code behoben werden. Siehe auch den Artikel zum automatischen Neustart im Hilfe-Center.

SUBDOMAIN

Veröffentlicht die Anwendung als Website unter https://<subdomain>.squareweb.app.

SUBDOMAIN=mysite

Bis zu 63 Zeichen: Buchstaben, Ziffern und Bindestriche, weder am Anfang noch am Ende ein Bindestrich. Der Name wird in Kleinbuchstaben gespeichert.
Ein Name, der bereits vergeben, reserviert (etwa admin oder api) oder ungültig ist, führt zu INVALID_SUBDOMAIN.
Eine Website braucht mehr RAM als ein Bot: siehe den Mindest-RAM.
Dein Server muss auf Port 80 und Host 0.0.0.0 lauschen (siehe Website lädt nicht).

Entscheide beim ersten Upload, ob die Anwendung eine Website ist. Bei einer Website kannst du die Subdomain später ändern, aber nicht entfernen (CANNOT_SET_SUBDOMAIN). Eine Anwendung, die ohne SUBDOMAIN deployt wurde, kann keine Website werden: Lade sie erneut als neue Anwendung mit gesetzter SUBDOMAIN hoch.

Um die Website unter deiner eigenen Domain bereitzustellen, lies im Hilfe-Center, wie du deine eigene Domain einrichtest.

RUNTIME

Legt die Runtime ausdrücklich fest, statt sie aus der Endung von MAIN abzuleiten. Ein unbekannter Wert führt zu INVALID_RUNTIME.

RUNTIME=nodejs

Runtime	Akzeptierte Werte
Node.js	`nodejs`, `javascript`
TypeScript	`typescript`
Python	`python`
C# / .NET	`csharp`, `dotnet`, `c#`
Elixir	`elixir`
Java	`java`
Rust	`rust`
Ruby	`ruby`
PHP	`php`
Go	`go`, `golang`
Statisches HTML/CSS	`static`, `html`

Mit gesetztem RUNTIME kannst du MAIN weglassen. Setze dann auch START: Die meisten Runtimes starten die Anwendung, indem sie die MAIN-Datei ausführen.

START

Ein eigener Startbefehl. Er ersetzt den Standardbefehl, der deine MAIN-Datei ausführt.

START=npm run start

Bis zu 256 Zeichen (darüber hinaus INVALID_START).
Die Abhängigkeiten werden trotzdem installiert, bevor der Befehl läuft.
Der Befehl wird bei jedem Start aus der Datei gelesen, du kannst ihn also ändern, indem du squarecloud.app im Dashboard bearbeitest und neu startest.

Rufe nur Skripte auf, die in deinem Projekt existieren. START=npm run build && npm run start schlägt zum Beispiel bei einer Express-App ohne build-Skript in der package.json fehl. Lass START weg, wenn der Standardbefehl ausreicht.

ID

Diesen Schlüssel schreibst du nicht selbst. Nach squarecloud upload fügt die Square Cloud CLI ID=<app ID> in die Datei ein, damit spätere Befehle wie squarecloud commit wissen, welche Anwendung gemeint ist. Square Cloud ignoriert ihn beim Deploy.

Beispiele

Bot

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=Robin bot
DESCRIPTION=Moderation and music for my server.
AUTORESTART=true

Website oder API

squarecloud.app

MAIN=index.js
MEMORY=512
VERSION=recommended
DISPLAY_NAME=My site
DESCRIPTION=My site is really cool!
SUBDOMAIN=mysite
AUTORESTART=true

Die Website antwortet unter https://mysite.squareweb.app.

Next.js

Ein Framework mit Build-Schritt verwendet START. Hier wählt MAIN nur die Node.js-Runtime aus, lass es also auf deine tatsächliche Konfigurationsdatei zeigen (etwa next.config.mjs); die Build- und Startskripte kommen aus der package.json.

squarecloud.app

MAIN=next.config.js
MEMORY=2048
VERSION=recommended
DISPLAY_NAME=Nextjs site
SUBDOMAIN=nextjs
START=npm run build && npm run start
AUTORESTART=true

Nächste Schritte

Umgebungsvariablen

Tokens und Verbindungs-Strings aus deinem Code und deiner ZIP-Datei heraushalten.

squarecloud.ignore

Festlegen, welche Dateien die CLI und VS Code beim Upload weglassen.

Runtimes

Versionen, Abhängigkeitsdateien und wie jede Runtime deine App startet.

Fehlerbehebung

Was jeder Deploy-Fehler bedeutet und wie du ihn behebst.

Dienste

Fehlerbehebung

Runtimes

Plattform

Changelog

Referenz der squarecloud.app-Konfigurationsdatei

Was ist die Konfigurationsdatei?

Die Konfigurationsdatei erstellen

Konfigurationsparameter

MAIN

MEMORY

VERSION

DISPLAY_NAME

DESCRIPTION

AUTORESTART

SUBDOMAIN

RUNTIME

START

ID

Beispiele

Bot

Website oder API

Next.js

Nächste Schritte

Umgebungsvariablen

squarecloud.ignore

Runtimes

Fehlerbehebung

​Was ist die Konfigurationsdatei?

​Die Konfigurationsdatei erstellen

​Konfigurationsparameter

​MAIN

​MEMORY

​VERSION

​DISPLAY_NAME

​DESCRIPTION

​AUTORESTART

​SUBDOMAIN

​RUNTIME

​START

​ID

​Beispiele

​Bot

​Website oder API

​Next.js

​Nächste Schritte

Umgebungsvariablen

squarecloud.ignore

Runtimes

Fehlerbehebung

Was ist die Konfigurationsdatei?

Die Konfigurationsdatei erstellen

Konfigurationsparameter

MAIN

MEMORY

VERSION

DISPLAY_NAME

DESCRIPTION

AUTORESTART

SUBDOMAIN

RUNTIME

START

ID

Beispiele

Bot

Website oder API

Next.js

Nächste Schritte