Empty Service - Ardor Docs

Overview

Create a service from scratch when you want complete control over your codebase. Start with an empty project, write your code, and define exactly how your application builds and runs.

Cerebrum can build it for you. Describe what you want — “create a REST API with user auth” — and Cerebrum will write the code, Dockerfile, and configuration. The details below are for when you want to understand or do it manually.

When to use this: Building custom applications, APIs, or services where you want to write all the code yourself or have Cerebrum help you build from a blank slate.

Why Start Empty

Full control

You decide everything — language, framework, dependencies, and architecture.

Clean slate

No legacy code or opinions. Build exactly what you need.

Cerebrum-powered

Let Cerebrum write your code, or do it yourself. Your choice.

Any language

Python, Node.js, Go, Rust, Java — anything that runs in a container.

Best for: Custom APIs, web applications, microservices, and any project where you’re writing the code from scratch.

Before You Start

You'll need a Dockerfile

Empty services require a Dockerfile in the project root to deploy. The dev container works without one, but deployments need it.

Know your stack

Decide on your programming language and framework before starting. This helps Cerebrum assist you more effectively.

Dev container available immediately

The development container starts right away with a terminal. You can install dependencies and run code before writing a Dockerfile.

Export to GitHub later

You can always connect your service to GitHub later to enable version control and local development.

How to create

1. Add Service
2. Service Created

Click Add Service → select Empty Service

Service appears with a default name (e.g., Service 1) — rename it to something descriptive

Project Structure

An empty service should start with a minimal structure. Here’s how to organize your code:

Python
Node.js
Go

/
├── app.py                 # Main application
├── requirements.txt       # Dependencies
└── Dockerfile            # Build instructions

/
├── src/
│   └── index.js          # Main application
├── package.json          # Dependencies
└── Dockerfile            # Build instructions

/
├── main.go               # Main application
├── go.mod                # Dependencies
└── Dockerfile            # Build instructions

Adding Your First Code

Step 1: Open the Code Editor

Click Code Editor in the toolbar to access your project files. Create your main application file.

Step 2: Write Your Application

Here’s a minimal “Hello World” for common languages:

Python (Flask)
Node.js (Express)
Go

app.py

import os
from flask import Flask

app = Flask(__name__)
port = int(os.environ.get('PORT', 8080))

@app.route('/')
def hello():
    return {'message': 'Hello from Ardor!'}

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=port)

requirements.txt

flask==3.0.0

src/index.js

const express = require('express');
const app = express();
const port = process.env.PORT || 8080;

app.get('/', (req, res) => {
  res.json({ message: 'Hello from Ardor!' });
});

app.listen(port, '0.0.0.0', () => {
  console.log(`Server running on port ${port}`);
});

package.json

{
  "name": "my-service",
  "version": "1.0.0",
  "main": "src/index.js",
  "scripts": {
    "start": "node src/index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

main.go

package main

import (
    "encoding/json"
    "net/http"
    "os"
)

func main() {
    port := os.Getenv("PORT")
    if port == "" {
        port = "8080"
    }

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "application/json")
        json.NewEncoder(w).Encode(map[string]string{
            "message": "Hello from Ardor!",
        })
    })

    http.ListenAndServe("0.0.0.0:"+port, nil)
}

go.mod

module myservice

go 1.21

Always bind to 0.0.0.0, not localhost or 127.0.0.1. This allows the container to accept external connections.

Dockerfile Setup

Create a Dockerfile in your project root for deployments:

Python
Node.js
Go

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

CMD ["python", "app.py"]

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 8080

CMD ["npm", "start"]

FROM golang:1.21-alpine AS builder

WORKDIR /app
COPY . .
RUN go build -o main .

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/main .

EXPOSE 8080

CMD ["./main"]

Dockerfile Requirements

Your Dockerfile must:

EXPOSE the port your app listens on
CMD or ENTRYPOINT to start your application
Read PORT from environment variable for flexibility

Best Practices

Start with the dev container

Use the terminal to prototype and test before writing the Dockerfile. It’s faster for iteration.

Use environment variables

Never hardcode configuration. Use os.environ (Python), process.env (Node.js), or os.Getenv (Go).

Keep images small

Use slim/alpine base images. Multi-stage builds reduce final image size significantly.

Pin dependency versions

Lock versions in requirements.txt, package-lock.json, or go.sum for reproducible builds.

Add health checks

Implement a /health endpoint for monitoring. Ardor uses this to verify your service is running.

Troubleshooting

Dockerfile not found

Cause: Missing Dockerfile in project root.Solution: Create a Dockerfile (case-sensitive) in the root directory, not in a subdirectory.

Build fails with dependency errors

Cause: Missing or incompatible dependencies.Solution:

Verify your dependency file exists (requirements.txt, package.json, etc.)
Test dependency installation in the dev container first
Check for version conflicts

App not accessible after deploy

Cause: Port mismatch or binding to localhost.Solution:

Ensure your app reads the PORT environment variable
Bind to 0.0.0.0, not localhost
Verify the EXPOSE port matches your app’s port

Changes not reflecting in dev container

Cause: Need to restart the container or app.Solution:

For code changes: Restart your app process
For dependency changes: Restart the dev container
Some frameworks support hot reload — configure them for faster iteration

What’s Next

Connect to GitHub

Version control your code and enable local development with your IDE

Add Environment Variables

Configure secrets and environment-specific settings

Networking

Configure public/private access and connect to other services

Variables & Secrets

Store API keys, passwords, and configuration securely

Documentation Index

​Overview

​Why Start Empty

Full control

Clean slate

Cerebrum-powered

Any language

​Before You Start

​How to create

​Project Structure

​Adding Your First Code

​Step 1: Open the Code Editor

​Step 2: Write Your Application

​Dockerfile Setup

Dockerfile Requirements

​Best Practices

​Troubleshooting

​What’s Next

Connect to GitHub

Add Environment Variables

Networking

Variables & Secrets

Overview

Why Start Empty

Before You Start

How to create

Project Structure

Adding Your First Code

Step 1: Open the Code Editor

Step 2: Write Your Application

Dockerfile Setup

Best Practices

Troubleshooting

What’s Next