Deploying Lowdefy

Introduction

Lowdefy is an open-source low-code framework that lets you build web applications using YAML or JSON configuration files. Instead of writing traditional code, you describe your application’s structure, data connections, and logic in configuration files, and Lowdefy generates a fully functional web application. This approach dramatically accelerates development for admin panels, BI dashboards, workflows, and CRUD applications.

Built on Next.js, Lowdefy combines the simplicity of configuration-driven development with the power and flexibility of modern web technologies. The framework includes over 100 pre-built blocks for building user interfaces, connections to popular databases and APIs, and built-in authentication powered by Auth.js.

Key highlights of Lowdefy:

• YAML/JSON Configuration: Build apps without writing JavaScript
• 100+ UI Blocks: Pre-built components for forms, tables, charts, and more
• Data Connections: Connect to PostgreSQL, MongoDB, MySQL, REST APIs, GraphQL, and more
• Built-in Authentication: Auth.js integration with multiple providers
• Real-Time Updates: Live data refresh and reactive interfaces
• Serverless Ready: Deploy to Vercel, Netlify, or Docker
• Extensible: Add custom blocks and connections when needed
• Type-Safe: Full TypeScript support with schema validation
• Version Control: Store configuration in Git for collaboration
• Open Source: Apache 2.0 licensed with active development

This guide walks through deploying Lowdefy on Klutch.sh using Docker, configuring your application, and connecting to data sources.

Why Deploy Lowdefy on Klutch.sh

Deploying Lowdefy on Klutch.sh provides several advantages:

Full Control: Self-hosting gives you complete control over your application and data.

Persistent Storage: Attach persistent volumes for configuration and application data.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access.

GitHub Integration: Connect your configuration repository directly from GitHub for automatic deployments.

Custom Domains: Use your own domain for your Lowdefy applications.

Scalable Resources: Allocate CPU and memory based on your application complexity and user load.

Environment Variable Security: Store database credentials and API keys securely.

Production Ready: Docker deployment provides a reliable production environment.

Prerequisites

Before deploying Lowdefy on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Lowdefy app
• Basic familiarity with YAML and Docker
• (Optional) Database credentials for data connections
• (Optional) A custom domain

Understanding Lowdefy Architecture

Lowdefy uses a modern architecture built on Next.js:

Configuration Layer: YAML/JSON files define your entire application structure, pages, data connections, and logic.

Next.js Runtime: The configuration is compiled into a Next.js application, providing server-side rendering and API routes.

Block System: UI components (blocks) are rendered based on your configuration, with over 100 pre-built options.

Connection System: Data connections handle communication with databases, APIs, and other services.

Authentication: Built-in Auth.js integration provides flexible authentication options.

Preparing Your Repository

To deploy Lowdefy on Klutch.sh, create a GitHub repository containing your Lowdefy app.

Repository Structure

lowdefy-app/
├── lowdefy.yaml
├── pages/
│   ├── home.yaml
│   └── users.yaml
├── Dockerfile
└── .dockerignore

Creating the Lowdefy Configuration

Create your main lowdefy.yaml:

lowdefy: 4.0.0

name: My Lowdefy App

config:
  auth:
    pages:
      signIn: /login
    providers:
      - id: credentials
        type: CredentialsProvider
        properties:
          name: Credentials
          credentials:
            username: { label: "Username", type: "text" }
            password: { label: "Password", type: "password" }

connections:
  - id: postgres
    type: PostgreSQL
    properties:
      connectionString:
        _secret: DATABASE_URL

menus:
  - id: main
    links:
      - id: home
        type: MenuLink
        properties:
          title: Home
          icon: AiOutlineHome
        pageId: home
      - id: users
        type: MenuLink
        properties:
          title: Users
          icon: AiOutlineUser
        pageId: users

pages:
  - _ref: pages/home.yaml
  - _ref: pages/users.yaml

Creating a Page

Create pages/home.yaml:

id: home
type: PageHeaderMenu
properties:
  title: Dashboard

blocks:
  - id: welcome
    type: Title
    properties:
      content: Welcome to Lowdefy

  - id: stats_row
    type: Box
    layout:
      contentGutter: 16
    blocks:
      - id: stat1
        type: Statistic
        properties:
          title: Total Users
          value: 1,234
          suffix: users

      - id: stat2
        type: Statistic
        properties:
          title: Active Sessions
          value: 56
          suffix: sessions

Creating the Dockerfile

Create a Dockerfile using Lowdefy’s init-docker command output:

FROM node:20-alpine AS builder

# Install dependencies
RUN apk add --no-cache libc6-compat

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci

# Copy Lowdefy configuration
COPY . .

# Build the application
RUN npm run build

# Production stage
FROM node:20-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

# Copy built application
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000

ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

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

Creating Package.json

Create a package.json:

{
  "name": "lowdefy-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "lowdefy dev",
    "build": "lowdefy build-next && next build",
    "start": "next start"
  },
  "dependencies": {
    "@lowdefy/server": "^4.0.0",
    "next": "^14.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "lowdefy": "^4.0.0"
  }
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules
.next

Environment Variables Reference

Lowdefy uses secrets for sensitive configuration:

Variable	Required	Description
DATABASE_URL	If using DB	Database connection string
NEXTAUTH_SECRET	Yes	Auth.js secret key
NEXTAUTH_URL	Yes	Public URL of your app

Secrets in Lowdefy are referenced with _secret:

properties:
  connectionString:
    _secret: DATABASE_URL

Deploying Lowdefy on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Generate Secrets

Generate required secrets:

# NextAuth secret
openssl rand -base64 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add .
git commit -m "Initial Lowdefy app"
git remote add origin https://github.com/yourusername/lowdefy-app.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “lowdefy-app” or “admin-panel”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Lowdefy app.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

In the environment variables section:

Variable	Value
NEXTAUTH_SECRET	Your generated secret
NEXTAUTH_URL	https://your-app-name.klutch.sh
DATABASE_URL	Your database connection string (if needed)

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the Lowdefy container
• Provision an HTTPS certificate

Access Your App

Once deployment completes, access your Lowdefy app at https://your-app-name.klutch.sh.

Building with Lowdefy

Pages and Layout

Create pages with various layouts:

id: dashboard
type: PageHeaderMenu
properties:
  title: Dashboard
  logo:
    src: /logo.png

areas:
  header:
    blocks:
      - id: title
        type: Title
        properties:
          content: My Application

  content:
    blocks:
      - id: main_content
        type: Box
        blocks:
          # Your content blocks

Forms and Inputs

Build forms with validation:

id: user_form
type: Box
blocks:
  - id: name
    type: TextInput
    required: true
    properties:
      title: Name
      placeholder: Enter name

  - id: email
    type: TextInput
    required: true
    properties:
      title: Email
      placeholder: Enter email

  - id: submit
    type: Button
    properties:
      title: Submit
      icon: AiOutlineSave
    events:
      onClick:
        - id: save_user
          type: Request
          params: save_user_request

Data Tables

Display data in tables:

id: users_table
type: AgGridAlpine
properties:
  rowData:
    _request: get_users
  columnDefs:
    - field: id
      headerName: ID
      width: 80
    - field: name
      headerName: Name
    - field: email
      headerName: Email
    - field: created_at
      headerName: Created

Charts and Visualization

Add charts to your dashboards:

id: sales_chart
type: EChart
properties:
  height: 400
  option:
    title:
      text: Monthly Sales
    xAxis:
      type: category
      data:
        _request: get_months
    yAxis:
      type: value
    series:
      - data:
          _request: get_sales
        type: bar

Data Connections

PostgreSQL

Connect to PostgreSQL:

connections:
  - id: postgres
    type: PostgreSQL
    properties:
      connectionString:
        _secret: DATABASE_URL

requests:
  - id: get_users
    type: PostgresQuery
    connectionId: postgres
    properties:
      query: SELECT * FROM users ORDER BY created_at DESC

MongoDB

Connect to MongoDB:

connections:
  - id: mongodb
    type: MongoDB
    properties:
      connectionString:
        _secret: MONGODB_URI
      database: myapp

requests:
  - id: get_documents
    type: MongoDBFind
    connectionId: mongodb
    properties:
      collection: documents
      query: {}

REST API

Connect to REST APIs:

connections:
  - id: api
    type: AxiosHttp
    properties:
      baseURL: https://api.example.com
      headers:
        Authorization:
          _string:
            template: "Bearer {{ secret }}"
            on:
              secret:
                _secret: API_KEY

requests:
  - id: get_data
    type: AxiosGet
    connectionId: api
    properties:
      url: /data

Authentication

Configuring Auth.js

Set up authentication in lowdefy.yaml:

config:
  auth:
    pages:
      signIn: /login
      error: /auth/error
    callbacks:
      session:
        _function:
          __session:
            user:
              __user:
    providers:
      - id: google
        type: GoogleProvider
        properties:
          clientId:
            _secret: GOOGLE_CLIENT_ID
          clientSecret:
            _secret: GOOGLE_CLIENT_SECRET

Protected Pages

Protect pages requiring authentication:

id: admin
type: PageHeaderMenu
auth:
  public: false
properties:
  title: Admin Dashboard

Production Best Practices

Security Recommendations

• Secret Management: Use Klutch.sh environment variables for all secrets
• Authentication: Implement proper authentication for all non-public pages
• Input Validation: Validate all user inputs in your configuration
• Connection Security: Use TLS for all database connections

Performance Optimization

• Data Caching: Implement caching for frequently accessed data
• Pagination: Use pagination for large data sets
• Selective Fields: Only query fields you need
• CDN: Use CDN for static assets

Monitoring

• Error Logging: Review Next.js logs for errors
• Performance Metrics: Monitor page load times
• Database Queries: Track slow queries

Troubleshooting Common Issues

Build Errors

Symptoms: Docker build fails.

Solutions:

• Validate YAML syntax
• Check for missing references
• Verify Lowdefy version compatibility
• Review build logs

Authentication Issues

Symptoms: Cannot log in or sessions expire.

Solutions:

• Verify NEXTAUTH_SECRET is set
• Check NEXTAUTH_URL matches your domain
• Review provider configuration

Database Connection Errors

Symptoms: Requests fail with connection errors.

Solutions:

• Verify connection string format
• Check database accessibility
• Review secret name matching
• Test connection directly

Additional Resources

• Lowdefy GitHub Repository
• Lowdefy Documentation
• Lowdefy Docker Deployment
• Lowdefy Docker Example
• Klutch.sh Deployments

Conclusion

Deploying Lowdefy on Klutch.sh gives you a powerful low-code platform for building internal tools and admin panels. The YAML-based configuration approach dramatically accelerates development while the Next.js runtime ensures production-quality performance.

With connections to popular databases, built-in authentication, and over 100 UI components, Lowdefy handles the complexity of web development so you can focus on your application logic. The self-hosted approach provides complete control over your applications and data.

Whether you’re building an admin panel, BI dashboard, or internal workflow tool, Lowdefy on Klutch.sh provides the foundation for rapid application development with enterprise-grade hosting.