Skip to main content

Deployxa Tutorials

Hands-on, step-by-step tutorials for common workflows and use cases.

Available Tutorials​

Getting Started​

  1. Deploy a Next.js Blog - Build and deploy a complete blog
  2. Deploy Laravel with Database - Full-stack PHP application
  3. Deploy Django with PostgreSQL - Python web application

Configuration​

  1. Connect GitHub - Set up GitHub integration
  2. Configure DNS - Set up custom domains
  3. Add SSL Certificate - Enable HTTPS (Coming Soon)

Operations​

  1. Rollback Deployment - Revert to previous version (Coming Soon)
  2. Setup Preview Deployments - Test before production (Coming Soon)
  3. Use Environment Variables - Manage configuration (Coming Soon)
  4. Use CLI - Command-line workflows (Coming Soon)
  5. Setup CI/CD - Continuous integration and deployment (Coming Soon)

Deploy a Next.js Blog​

Build and deploy a complete Next.js blog with markdown support.

What You'll Build​

A fully functional blog with:

  • Markdown-based posts
  • Dynamic routing
  • SEO optimization
  • Responsive design
  • Automatic deployment

Prerequisites​

  • Node.js 18+ installed
  • GitHub account
  • Deployxa account

Step 1: Create Next.js App​

npx create-next-app@latest my-blog --typescript --tailwind --app
cd my-blog

Step 2: Install Dependencies​

npm install gray-matter remark remark-html

Step 3: Create Blog Structure​

Create posts/ directory:

mkdir posts

Create a sample post posts/first-post.md:

---
title: "First Post"
date: "2024-01-15"
---

# Welcome to My Blog

This is my first blog post deployed with Deployxa!

## Features

- Markdown support
- Dynamic routing
- SEO optimization

Step 4: Create Blog Components​

Create lib/posts.ts:

import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';
import { remark } from 'remark';
import html from 'remark-html';

const postsDirectory = path.join(process.cwd(), 'posts');

export function getPostSlugs() {
  return fs.readdirSync(postsDirectory);
}

export async function getPostBySlug(slug: string) {
  const fullPath = path.join(postsDirectory, `${slug}.md`);
  const fileContents = fs.readFileSync(fullPath, 'utf8');
  const { data, content } = matter(fileContents);
  
  const processedContent = await remark()
    .use(html)
    .process(content);
  const contentHtml = processedContent.toString();
  
  return {
    slug,
    contentHtml,
    ...data,
  };
}

export async function getAllPosts() {
  const slugs = getPostSlugs();
  const posts = await Promise.all(
    slugs.map((slug) => getPostBySlug(slug))
  );
  return posts.sort((a, b) => (a.date > b.date ? -1 : 1));
}

Step 5: Create Blog Pages​

Create app/page.tsx:

import { getAllPosts } from '@/lib/posts';
import Link from 'next/link';

export default async function Home() {
  const posts = await getAllPosts();
  
  return (
    <main className="max-w-4xl mx-auto px-4 py-8">
      <h1 className="text-4xl font-bold mb-8">My Blog</h1>
      <div className="space-y-8">
        {posts.map((post) => (
          <article key={post.slug} className="border-b pb-8">
            <Link href={`/posts/${post.slug}`}>
              <h2 className="text-2xl font-semibold hover:text-blue-600">
                {post.title}
              </h2>
            </Link>
            <p className="text-gray-600 mt-2">{post.date}</p>
          </article>
        ))}
      </div>
    </main>
  );
}

Create app/posts/[slug]/page.tsx:

import { getPostBySlug, getPostSlugs } from '@/lib/posts';

export async function generateStaticParams() {
  const slugs = getPostSlugs();
  return slugs.map((slug) => ({ slug: slug.replace('.md', '') }));
}

export default async function Post({ params }: { params: { slug: string } }) {
  const post = await getPostBySlug(params.slug);
  
  return (
    <article className="max-w-4xl mx-auto px-4 py-8">
      <h1 className="text-4xl font-bold mb-4">{post.title}</h1>
      <p className="text-gray-600 mb-8">{post.date}</p>
      <div 
        className="prose prose-lg"
        dangerouslySetInnerHTML={{ __html: post.contentHtml }}
      />
    </article>
  );
}

Step 6: Push to GitHub​

git init
git add .
git commit -m "Initial blog setup"
git remote add origin https://github.com/yourusername/my-blog.git
git push -u origin main

Step 7: Deploy to Deployxa​

  1. Go to Deployxa Dashboard
  2. Click "New Project"
  3. Select your GitHub repository
  4. Deployxa detects Next.js automatically
  5. Click "Deploy"

Your blog is live in under 60 seconds!

Step 8: Add Custom Domain (Optional)​

  1. Go to Project → Domains
  2. Click "Add Domain"
  3. Enter your domain (e.g., blog.example.com)
  4. Configure DNS records
  5. Wait for verification

Next Steps​

  • Add more posts to the posts/ directory
  • Customize the design with Tailwind CSS
  • Add categories and tags
  • Implement search functionality
  • Add comments system

Deploy Laravel with Database​

Deploy a full-stack Laravel application with MySQL database.

What You'll Build​

A complete Laravel application with:

  • User authentication
  • Database models
  • API endpoints
  • Automatic migrations
  • Production-ready configuration

Prerequisites​

  • PHP 8.1+ installed locally
  • Composer installed
  • MySQL/MariaDB (for local development)
  • GitHub account
  • Deployxa account

Step 1: Create Laravel App​

composer create-project laravel/laravel my-laravel-app
cd my-laravel-app

Step 2: Configure for Production​

Update .env.example:

APP_NAME=MyLaravelApp
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://your-app.deployxa.app

LOG_CHANNEL=stack
LOG_LEVEL=error

DB_CONNECTION=mysql
DB_HOST=${DB_HOST}
DB_PORT=3306
DB_DATABASE=${DB_NAME}
DB_USERNAME=${DB_USER}
DB_PASSWORD=${DB_PASSWORD}

Step 3: Create Database Models​

Create a simple Post model:

php artisan make:model Post -mcr

Update database/migrations/xxxx_create_posts_table.php:

public function up()
{
    Schema::create('posts', function (Blueprint $table) {
        $table->id();
        $table->string('title');
        $table->text('content');
        $table->foreignId('user_id')->constrained();
        $table->timestamps();
    });
}

Update app/Models/Post.php:

protected $fillable = ['title', 'content', 'user_id'];

public function user()
{
    return $this->belongsTo(User::class);
}

Step 4: Create API Routes​

Update routes/api.php:

use App\Http\Controllers\PostController;

Route::apiResource('posts', PostController::class);

Step 5: Configure for Deployxa​

Create config/deployxa.php:

<?php

return [
    'build_command' => 'composer install --no-dev --optimize-autoloader',
    'post_deploy' => [
        'php artisan migrate --force',
        'php artisan config:cache',
        'php artisan route:cache',
        'php artisan view:cache',
    ],
];

Step 6: Push to GitHub​

git init
git add .
git commit -m "Initial Laravel setup"
git remote add origin https://github.com/yourusername/my-laravel-app.git
git push -u origin main

Step 7: Deploy to Deployxa​

  1. Go to Deployxa Dashboard
  2. Click "New Project"
  3. Select your GitHub repository
  4. Deployxa detects Laravel automatically
  5. Click "Deploy"

Step 8: Set Up Database​

  1. Go to Project → Settings → Database
  2. Click "Create Database"
  3. Choose MySQL
  4. Copy connection details

Step 9: Add Environment Variables​

  1. Go to Project → Environment
  2. Add database credentials:
DB_HOST=your-db-host
DB_NAME=your-database
DB_USER=your-username
DB_PASSWORD=your-password
APP_KEY=your-app-key
  1. Redeploy application

Step 10: Run Migrations​

Deployxa automatically runs migrations on deployment. Verify in logs:

php artisan migrate --force

Next Steps​

  • Add user authentication with Laravel Breeze
  • Implement file uploads
  • Add queue workers for background jobs
  • Set up scheduled tasks
  • Configure email sending

Deploy Django with PostgreSQL​

Deploy a Django application with PostgreSQL database.

What You'll Build​

A complete Django application with:

  • REST API
  • PostgreSQL database
  • User authentication
  • Admin interface
  • Production settings

Prerequisites​

  • Python 3.10+ installed
  • pip installed
  • PostgreSQL (for local development)
  • GitHub account
  • Deployxa account

Step 1: Create Django Project​

pip install django djangorestframework psycopg2-binary gunicorn
django-admin startproject myproject
cd myproject
python manage.py startapp api

Step 2: Configure Settings​

Update myproject/settings.py:

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = os.environ.get('SECRET_KEY', 'your-secret-key')
DEBUG = os.environ.get('DEBUG', 'False') == 'True'
ALLOWED_HOSTS = os.environ.get('ALLOWED_HOSTS', '').split(',')

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'api',
]

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ.get('DB_NAME'),
        'USER': os.environ.get('DB_USER'),
        'PASSWORD': os.environ.get('DB_PASSWORD'),
        'HOST': os.environ.get('DB_HOST'),
        'PORT': os.environ.get('DB_PORT', '5432'),
    }
}

STATIC_ROOT = BASE_DIR / 'staticfiles'
STATIC_URL = '/static/'

Step 3: Create Models​

Update api/models.py:

from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    
    def __str__(self):
        return self.title

Step 4: Create Serializers​

Create api/serializers.py:

from rest_framework import serializers
from .models import Article

class ArticleSerializer(serializers.ModelSerializer):
    class Meta:
        model = Article
        fields = ['id', 'title', 'content', 'created_at', 'updated_at']

Step 5: Create Views​

Update api/views.py:

from rest_framework import viewsets
from .models import Article
from .serializers import ArticleSerializer

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer

Step 6: Configure URLs​

Update api/urls.py:

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ArticleViewSet

router = DefaultRouter()
router.register(r'articles', ArticleViewSet)

urlpatterns = [
    path('', include(router.urls)),
]

Update myproject/urls.py:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('api.urls')),
]

Step 7: Create requirements.txt​

pip freeze > requirements.txt

Ensure it includes:

Django>=4.2
djangorestframework>=3.14
psycopg2-binary>=2.9
gunicorn>=21.2

Step 8: Create Procfile​

Create Procfile:

web: gunicorn myproject.wsgi:application --bind 0.0.0.0:$PORT

Step 9: Push to GitHub​

git init
git add .
git commit -m "Initial Django setup"
git remote add origin https://github.com/yourusername/myproject.git
git push -u origin main

Step 10: Deploy to Deployxa​

  1. Go to Deployxa Dashboard
  2. Click "New Project"
  3. Select your GitHub repository
  4. Deployxa detects Django automatically
  5. Click "Deploy"

Step 11: Set Up Database​

  1. Go to Project → Settings → Database
  2. Click "Create Database"
  3. Choose PostgreSQL
  4. Copy connection details

Step 12: Add Environment Variables​

  1. Go to Project → Environment
  2. Add variables:
SECRET_KEY=your-secret-key
DEBUG=False
ALLOWED_HOSTS=your-app.deployxa.app
DB_HOST=your-db-host
DB_NAME=your-database
DB_USER=your-username
DB_PASSWORD=your-password
DB_PORT=5432
  1. Redeploy application

Step 13: Run Migrations​

Deployxa automatically runs migrations. Verify in logs:

python manage.py migrate

Step 14: Create Superuser​

Access Django shell:

python manage.py createsuperuser

Next Steps​

  • Add user authentication
  • Implement permissions
  • Add pagination
  • Set up caching
  • Configure CORS
  • Add API documentation with Swagger

Connect GitHub​

Set up GitHub integration for automatic deployments.

What You'll Learn​

  • Connect your GitHub account
  • Grant repository access
  • Enable automatic deployments
  • Configure branch protection

Step 1: Access GitHub Settings​

  1. Go to Deployxa Dashboard
  2. Click your profile icon
  3. Select "Settings"
  4. Click "GitHub Integration"

Step 2: Connect GitHub​

  1. Click "Connect GitHub"
  2. You'll be redirected to GitHub
  3. Review permissions
  4. Click "Authorize Deployxa"

Step 3: Grant Repository Access​

Option A: All Repositories

  • Select "All repositories"
  • Click "Save"

Option B: Specific Repositories

  • Select "Only select repositories"
  • Choose repositories to grant access
  • Click "Save"

Step 4: Verify Connection​

  1. Return to Deployxa dashboard
  2. Check GitHub connection status
  3. Verify repositories are listed

Step 5: Create Project from GitHub​

  1. Click "New Project"
  2. Select "GitHub"
  3. Choose repository
  4. Select branch
  5. Click "Create Project"

Step 6: Enable Automatic Deployments​

  1. Go to Project → Settings → Deployments
  2. Enable "Auto-deploy on push"
  3. Select branches to auto-deploy
  4. Click "Save"

Step 7: Configure Branch Protection (Optional)​

  1. Go to your GitHub repository
  2. Click "Settings" → "Branches"
  3. Add branch protection rule
  4. Require pull request reviews
  5. Enable status checks

Step 8: Test Deployment​

  1. Make a change to your code
  2. Commit and push to GitHub
  3. Watch deployment trigger automatically
  4. Verify deployment succeeds

Troubleshooting​

GitHub not showing repositories:

  • Verify GitHub connection
  • Check repository permissions
  • Refresh the page

Deployment not triggering:

  • Verify auto-deploy is enabled
  • Check branch name matches
  • Review webhook configuration

Permission denied:

  • Re-authorize GitHub
  • Check repository access
  • Verify organization permissions

Configure DNS​

Set up custom domains for your Deployxa projects.

What You'll Learn​

  • Add custom domains
  • Configure DNS records
  • Verify domain ownership
  • Enable SSL certificates

Step 1: Add Domain to Project​

  1. Go to Project → Domains
  2. Click "Add Domain"
  3. Enter your domain (e.g., example.com)
  4. Select domain type:
    • Apex domain: example.com
    • Subdomain: www.example.com
    • Wildcard: *.example.com
  5. Click "Add"

Step 2: Configure DNS Records​

For Apex Domain:

Add A record:

Type: A
Name: @
Value: 76.76.21.21
TTL: 3600

For Subdomain:

Add CNAME record:

Type: CNAME
Name: www
Value: cname.deployxa.com
TTL: 3600

For Wildcard:

Add CNAME record:

Type: CNAME
Name: *
Value: cname.deployxa.com
TTL: 3600

Step 3: Verify Domain​

  1. Go to Project → Domains
  2. Click "Verify" next to your domain
  3. Wait for verification (5-15 minutes)
  4. Check verification status

Step 4: Wait for SSL Certificate​

  1. SSL certificate is automatically provisioned
  2. Wait 1-5 minutes
  3. Check SSL status
  4. Verify HTTPS is working

Step 5: Test Domain​

  1. Visit your domain in browser
  2. Verify HTTPS is enabled
  3. Check SSL certificate
  4. Test all routes

Step 6: Set Up Redirects (Optional)​

Redirect non-www to www:

  1. Add both domains to project
  2. Set primary domain
  3. Configure redirect on non-primary domain

DNS Propagation​

Check propagation:

dig example.com A
dig www.example.com CNAME

Online tools:

Propagation time:

  • Typical: 5-15 minutes
  • Maximum: 48 hours

Troubleshooting​

Domain not verifying:

  • Check DNS records are correct
  • Wait for propagation
  • Verify domain name is correct
  • Try manual verification

SSL not provisioning:

  • Verify domain is verified
  • Check DNS records
  • Wait up to 5 minutes
  • Contact support if issue persists

Domain not loading:

  • Check domain is active
  • Verify SSL certificate
  • Clear browser cache
  • Check project is deployed

More tutorials coming soon!