This guide walks you through deploying a Next.js application from a GitHub repository to a production URL with a custom domain, SSL certificate, environment variables, and continuous deployment. The entire process takes under 10 minutes. By the end, every push to your main branch will automatically deploy to production.
Prerequisites
Before starting, you need:
This guide works with Next.js 13, 14, and 15 (App Router or Pages Router). The deployment process is the same for all versions.
Step 1: Connect your GitHub repository
Log in to your Arxentra dashboard. Click "New Service" and select "Web Application". Choose "Connect GitHub Repository" and authorize Arxentra to access your GitHub account.
Select the repository containing your Next.js app and the branch you want to deploy (typically `main` or `production`).
Q: Can I deploy from a monorepo?
Yes. When connecting a monorepo, set the "Root Directory" to the path of your Next.js app (e.g., `apps/web` or `packages/frontend`). Arxentra will only build and deploy from that directory.
Step 2: Configure build settings
Arxentra auto-detects Next.js applications and configures the build automatically. The detected settings will be:
- Framework: Next.js
- Build command: `npm run build`
- Start command: `npm start`
- Port: 3000
If you use a different package manager, Arxentra detects it from your lock file:
| Lock file | Package manager | Build command |
| package-lock.json | npm | `npm run build` |
| yarn.lock | yarn | `yarn build` |
| pnpm-lock.yaml | pnpm | `pnpm build` |
| bun.lockb | bun | `bun run build` |
You can override any of these settings. For example, if your build command is `npm run build:production`, update it in the build settings panel.
Step 3: Set environment variables
Click "Environment Variables" in the service configuration panel. Add your production environment variables:
<h1>Common Next.js environment variables</h1>
NEXT_PUBLIC_API_URL=https://api.yourdomain.com
NEXT_PUBLIC_APP_URL=https://yourdomain.com
DATABASE_URL=postgresql://user:password@host:5432/dbname
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=https://yourdomain.com
Important: Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Never put secrets (API keys, database URLs, auth secrets) in `NEXT_PUBLIC_` variables.
Q: How do I connect a database?
If you need a PostgreSQL database, create one from the Arxentra dashboard: go to "New Service" > "Database" > "PostgreSQL". Once created, link it to your Next.js service. The `DATABASE_URL` environment variable is automatically injected. See the Services Overview for database options.
Step 4: Deploy
Click "Deploy". Arxentra will:
First deployment typically takes 2-4 minutes. Subsequent deployments are faster due to dependency caching.
Q: What if the build fails?
Check the build logs in the "Deployments" tab. Common issues:
- Missing environment variables: Build-time variables (`NEXT_PUBLIC_*`) must be set before building
- Node.js version mismatch: Set the Node.js version in your `package.json` engines field or Arxentra settings
- Out of memory: Next.js builds can be memory-intensive. Upgrade to a plan with more RAM if builds fail with "JavaScript heap out of memory"
Step 5: Configure custom domain
Navigate to "Settings" > "Domains" for your service. Click "Add Custom Domain" and enter your domain (e.g., `app.yourdomain.com`).
Arxentra will display DNS records to add at your domain registrar:
| Record type | Name | Value |
| CNAME | app | your-service-name.arxentra.app |
For root domains (e.g., `yourdomain.com` without a subdomain):
| Record type | Name | Value |
| A | @ | (Arxentra IP address shown in dashboard) |
DNS propagation typically takes 5-30 minutes. Arxentra automatically provisions an SSL certificate via Let's Encrypt once DNS is verified. The certificate auto-renews every 60 days.
Q: Can I use Cloudflare with Arxentra?
Yes. If you use Cloudflare for DNS, add the CNAME record with Cloudflare proxy enabled (orange cloud). Set Cloudflare's SSL mode to "Full (Strict)" to avoid redirect loops. This gives you Cloudflare's CDN and DDoS protection in front of your Arxentra deployment.
Step 6: Set up continuous deployment
Continuous deployment is enabled by default. Every push to your connected branch triggers a new deployment. You can customize this behavior:
- Auto-deploy on push: Enabled by default. Disable in "Settings" > "Deployment" if you want manual deployments only.
- Deploy on PR merge only: Set the deploy branch to `main` and only merge PRs when ready to deploy.
- Preview deployments: Enable in "Settings" > "Preview Deploys". Every pull request gets a unique preview URL for testing before merge.
Q: How do I set up a CI/CD pipeline with GitHub Actions?
For most projects, Arxentra's built-in auto-deploy is sufficient. If you need custom CI/CD (running tests before deploy, multi-stage pipelines), use GitHub Actions with the Arxentra CLI:
<h1>.github/workflows/deploy.yml</h1>
name: Deploy to Arxentra
on:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm test
deploy:
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy to Arxentra
run: npx arx deploy --token ${{ secrets.ARXENTRA_TOKEN }}
Add your Arxentra API token as a GitHub Actions secret named `ARXENTRA_TOKEN`. Generate the token from your Arxentra dashboard under "Settings" > "API Tokens".
Step 7: Configure production optimizations
Once your deployment is live, configure these production optimizations:
Health checks: Arxentra automatically pings your application's `/` route. For custom health check endpoints:
// pages/api/health.js (Pages Router)
export default function handler(req, res) {
res.status(200).json({ status: 'ok', timestamp: new Date().toISOString() });
}
// app/api/health/route.js (App Router)
export async function GET() {
return Response.json({ status: 'ok', timestamp: new Date().toISOString() });
}
Set the health check path to `/api/health` in your service settings.
Scaling: Configure auto-scaling in "Settings" > "Scaling":
| Setting | Recommended value |
| Min replicas | 2 (for high availability) |
| Max replicas | 10 (adjust based on traffic) |
| Scale-up threshold | CPU > 70% for 60 seconds |
| Scale-down threshold | CPU < 30% for 300 seconds |
Caching: Add Cache-Control headers for static assets in your `next.config.js`:
// next.config.js
module.exports = {
async headers() {
return [
{
source: '/_next/static/:path*',
headers: [
{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' },
],
},
];
},
};
Troubleshooting FAQ
Q: My app deploys but shows a 502 error. What is wrong?
A 502 error means the container started but the application is not responding on the expected port. Check: (1) your app listens on the port specified in settings (default 3000), (2) it binds to `0.0.0.0`, not `localhost`, (3) the build completed successfully. Check logs in the "Deployments" tab for startup errors.
Q: Environment variables are not available in the browser. Why?
Only variables prefixed with `NEXT_PUBLIC_` are available client-side in Next.js. Server-side variables (API keys, database URLs) are intentionally hidden from the browser. If you added a `NEXT_PUBLIC_` variable after building, you need to redeploy because these values are embedded at build time.
Q: How do I use a specific Node.js version?
Add an `engines` field to your `package.json`:
{
"engines": {
"node": "20.x"
}
}
Arxentra respects this field and uses the specified Node.js version for builds and runtime.
Q: Can I deploy a Next.js app with ISR (Incremental Static Regeneration)?
Yes. ISR works on Arxentra because the Next.js server runs as a persistent container (not serverless). Pages revalidate on schedule as configured in your `revalidate` settings. This is one advantage of container-based hosting over serverless platforms where ISR requires additional infrastructure.
Q: How do I roll back to a previous deployment?
Go to the "Deployments" tab, find the deployment you want to restore, and click "Rollback". The previous version is restored within 30 seconds. Rollbacks use the previously-built container image, so they do not require a new build.
Q: Can I deploy a Next.js static export?
Yes. If you use `output: 'export'` in your `next.config.js`, Arxentra serves the static files through its CDN. Set the build command to `npm run build` and the output directory to `out/`. Static exports are served with edge caching for fast load times.
Q: How do I monitor my deployment?
Arxentra provides built-in monitoring for CPU, memory, network, and request metrics. View real-time charts in the service dashboard. Set up alerts for high CPU, memory, or error rate thresholds in "Settings" > "Alerts". For application-level monitoring, integrate your preferred APM tool (Sentry, Datadog, New Relic) using their Next.js SDK.
For more advanced deployment configurations, explore the Arxentra documentation. If you are considering other hosting options, compare with Vercel or Railway.