Getting Started — Clouderized Docs

How deployment works

Clouderized is a deployment remote — not a replacement for GitHub or GitLab. You keep your existing git workflow and simply push to Clouderized when you want to deploy. Every push to the main branch triggers an automatic build and deploy.

Add Clouderized as a remote

One git remote add command connects your existing repo.

Push to deploy

git push clouderized main — that's your entire deploy command.

Build runs automatically

Gitea Actions builds your Docker image. First build ~60s; subsequent pushes are faster.

Live at your URL

Your app is served at your-app.clouderized.com over HTTPS automatically.

Choose your path

Both paths reach the same result: your first live HTTPS endpoint. Pick the one that matches your comfort level.

First 15 minutes decide. This path keeps the first win simple and concrete.

VS Code / VSCodium Quick Start

Use the built-in terminal and copy/paste these commands

Goal: get your first win in about 15 minutes, then move to the full CLI workflow when you are ready.

Open your project

Open your app folder in VS Code or VSCodium.

Open terminal

Use Terminal > New Terminal.

Run deploy commands

Copy and run the block below. Then wait for your live app URL.

# In VS Code terminal, inside your project folder

git remote add clouderized https://git.clouderized.com/username/repo-name

git push clouderized main

First push only: You may be asked once for your git.clouderized.com username and password/token.

Expected result

Your app becomes live at https://username-repo-name.clouderized.com once the deploy workflow completes in Gitea Actions.

Step 1 — Add Clouderized as a remote

Run this once in your existing project directory

In your existing project (the one already on GitHub, GitLab, or your local machine), add Clouderized as a second remote. You'll keep pushing to GitHub/GitLab as normal — this is purely for deployments.

No need to create a repo first. Pushing automatically creates the repo on git.clouderized.com — just add the remote and push.

# Inside your existing project folder

git remote add clouderized https://git.clouderized.com/username/repo-name

Tip: Save your credentials so you're not prompted on every push:

git config --global credential.helper store

After running this, the next push will ask for your username and password once — then cache them.

Starting from scratch? If you don't have a local repo yet:

git init

git remote add clouderized https://git.clouderized.com/username/repo-name

Step 2 — Add a Dockerfile

Clouderized builds whatever Dockerfile it finds in your repo

Your repo needs a Dockerfile somewhere in the repository. Clouderized automatically finds and builds it — it can be at the root or in a subdirectory like backend/Dockerfile.

Not sure where to start? See our Sample Dockerfiles — ready-to-use templates for Python, Node.js, Go, Ruby, Java, and more.

A minimal example for a Node.js app:

FROM node:20-alpine

# Copy and install dependencies

WORKDIR /app

COPY package*.json ./

RUN npm ci --omit=dev

COPY . .

# Expose the port your app listens on

EXPOSE 3000

CMD ["node", "server.js"]

Important: The port in EXPOSE must match the port your app actually listens on. Clouderized reads this to configure routing automatically.

Step 3 — Push to deploy

Every push to main builds and deploys automatically

Push your code to the clouderized remote. Your first push provisions the app — subsequent pushes trigger a redeploy.

# Deploy to Clouderized

git push clouderized main

# Your GitHub/GitLab push stays the same as always

git push origin main

After your first push, do a pull before pushing again. The platform adds a deploy.yml workflow file to your repo automatically. Pull it down first so your local branch stays in sync:

git pull clouderized main --rebase

Want to deploy automatically on every push? Set up a GitHub/GitLab Actions step that runs git push clouderized main after your existing CI passes.

Step 4 — Watch it build

Go to your repo's Actions tab in Gitea to watch the build live:

Open the Actions tab

Go to https://git.clouderized.com/username/repo-name/actions

Click the running workflow

You'll see a Deploy workflow triggered by your push. Click it to view live logs.

Wait for the green tick

Once the workflow completes successfully, your app is live. First build takes ~60 seconds.

Open your app URL

Your app is live at https://username-repo-name.clouderized.com

Managing your app

The Clouderized dashboard lets you manage your app without touching the command line. Log in with your Gitea credentials via OAuth.

Status & metrics

View your app's current state, uptime, RAM and CPU usage in real time.

Start / Stop / Restart

Control your app lifecycle without a redeploy. Useful after changing env vars or debugging.

Deployment history

Jump straight to your app's Gitea Actions history to review past builds and logs.

Environment variables

Set key-value pairs that are injected into your container on each deploy.

File browser

Browse, upload, and manage files in your app's /app/data persistent storage directory.

Custom domains

Point your own domain to your app. Add a CNAME in your DNS and verify it in the Domains tab.

Frontend Companion

Serve a React, Vue, or Svelte SPA alongside your backend. Enable it in the Frontend tab and point it at your frontend source directory.

All requests starting with /api are proxied to your backend. Everything else is served as a static file, with a fallback to index.html for client-side routing. Your backend routes must be under /api — routes like /health or /auth/login will not reach the backend.

Troubleshooting

Build failed — what do I do?

Open the failed workflow in Gitea Actions and expand the failing step to see the error. Common causes: missing dependency in Dockerfile, wrong base image, or a build command that exits non-zero.

App built but returns 502 / won't load

Your app is probably not listening on the port declared in EXPOSE, or it's crashing on startup. Check the app logs in the dashboard and confirm your server binds to 0.0.0.0, not 127.0.0.1.

App was working, now it's sleeping

Starter plan apps sleep after 15 minutes of inactivity to conserve resources. They wake automatically on the next request — the first response after sleeping takes a few seconds longer. Pro plan apps never sleep.

Need help?

Email us at [email protected] — include your username and app name.

What's next?

Sample Dockerfiles

Ready-to-use templates for popular stacks.

Connecting to Databases

How credentials reach your container at runtime.

Persistent Storage

Using /app/data to keep files across deploys.

Custom Domains

Point your own domain to your app in three steps.

Planning to add a database?

Databases share your slot's resource pool. MariaDB needs at least 0.25 vCPU + 384 MB RAM; PostgreSQL needs at least 0.25 vCPU + 512 MB RAM. For an app + database together, plan for 2 × Starter or Pro. See resource planning for full allocation guidance.