Prerequisites

To create a project on Zenifra, you need:

• a created and verified account
• to be signed in to the console

Accessing Project Creation

In the console sidebar, click + Create Project.

Step 1: Choose the Project Type

Zenifra offers different application types for deployment:

HTTP Application

Ideal for:

• web applications (React, Vue, Angular)
• HTTP servers (Nginx, Apache)
• REST APIs
• Node.js and Python applications via GitHub Repository
• Java, Go, PHP, .NET, Nginx, Apache, and other stacks via OCI Image

Publishing methods

Zenifra offers two ways to publish an HTTP project:

• GitHub Repository: choose Project Source as GitHub Repository, then select the repository and branch. If you want every push to that branch to publish automatically, enable auto-deploy during creation. After creation, you can also edit the pre-build, build, and start commands on the edit project screen.
• OCI Image: provide a standard OCI image (Docker) to publish the application. In this flow, new versions are published by updating the image or tag in the console.

PostgreSQL Database

If you need a managed database, see our tutorial on how to create a PostgreSQL database.

Step 2: Select the Plan

Plans define the available resources and the price of your application. Each plan offers different levels of:

• CPU, Memory, and GPU
• free storage (when available)
• exclusive features (custom subdomain, IP blocklist, etc.)

Payment Models

Choose how you want to pay for your project:

Tip: In hourly billing, if your application runs only 10 minutes in the month, you pay only for 1 hour.

Step 3: Configure Basic Information

Project Name

The name is used to:

• identify your project on the dashboard
• create automatic subdomains

Name rules:

• Minimum: 6 characters
• Maximum: 32 characters
• Only lowercase letters, numbers, and hyphens
• Example: my-web-project, my-company-api

Description

Optional field to add information about the project. It helps organize and identify projects when you have many of them.

Step 4: Configure the Project Source

GitHub Repository

If you selected GitHub Repository, choose the repository, main branch, and application runtime. For Node.js and Python projects, review the pre-build, build, and start commands before creating the project.

auto-deploy is optional. When enabled, every push to the selected branch publishes a new version. When disabled, you control publishing manually from the console.

OCI Image

The OCI image is the template that will be used to create your instance. You can use public or private images.

Public Image

Images that do not require authentication to download. Examples:

docker.io/nginxinc/nginx-unprivileged:stable-alpine
docker.io/metabase/metabase:v0.50.0
docker.io/wordpress:6.5.3-php8.2-apache

For NGINX, use the nginxinc/nginx-unprivileged image because OCI images on Zenifra should not run the main process as root.

Private Image

For images in private registries, you need to configure authentication:

Option 1: AWS ECR

• AWS region where your repository is located
• Access Key ID and Secret Access Key
• Your AWS account ID

Option 2: Username and Token

• Registry username
• Access token or password

Important: Always use specific tags (such as v1.2.3) instead of latest. This ensures that your application always uses the same image version.

Step 5: Configure Port and Instances

Application Port

The port your application listens on internally. External traffic (HTTP/HTTPS on ports 80 and 443) is routed to that port.

Common ports by technology:

Number of Instances

Number of replicas for your application:

• 1 instance: ideal for low-traffic applications or testing
• 2+ instances: high availability and load balancing

Recommendation: For production applications, use at least 2 instances to improve availability in case of failures.

Step 6: Environment Variables

Environment variables (ENVs) are settings that your application can access at runtime. They are useful for:

• sensitive settings (API keys, passwords)
• external API URLs
• settings that change between environments

ENV examples:

DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=your-key-here
PORT=3000

Limit: Up to 50 environment variables per project.

Step 7: Configure Storage

Persistent Storage

Choose "Yes" if your application needs to:

• save files that should survive restarts
• keep user uploads

Choose "No" for applications where data is ephemeral (such as stateless web servers).

Note: Persistent storage data is replicated across 3 different instances. That means if you save a PDF file and, for some reason, a Zenifra server fails, your locally saved file still remains available.

Storage Capacity

• Minimum: 1 GB
• Maximum: 250 GB

Warning: In hourly billing, storage can only be increased, never reduced. For monthly or yearly contracts, storage cannot be changed after project creation.

Directory to Persist

Absolute path of the directory inside the container whose data will be saved:

/app/data
/var/lib/postgresql/data
/uploads

A common use case for the free storage included in the plan, when available, is storing files in /data, such as temporary imports, generated PDFs, reports, or other artifacts that can be deleted after use.

Important: You can choose the persisted folder when creating the project, but that path cannot be changed later.

Step 8: Configure Domains

Zenifra Subdomain

Plans above Basic include a custom subdomain in the following format:

your-project-sub-domain

Custom Domain

You can use your own domain (for example api.yourcompany.com) instead of the default subdomain, but this is configured after the project has already been created and is reachable through the default Zenifra domain.

To configure after creation:

1. Open the project settings
2. Add your custom domain (for example api.yourcompany.com)
3. For subdomains, such as api.yourcompany.com, configure a CNAME pointing to the subdomain created by Zenifra
4. For root domains, such as yourcompany.com, use CNAME only with a provider that supports CNAME flattening, or redirect the root to a subdomain such as www.yourcompany.com
5. Publish the SSL validation TXT records shown in the console, if requested

Limit: Up to 20 custom domains per project.

Step 9: Configure Network Access (Premium+ Plans)

This option is available only on specific plans.

Whitelist

Defines which IP addresses can access your project. Non-listed IPs are blocked.

CIDR format:

• 0.0.0.0/0 - Allows all IPs
• XXX.XXX.XXX.XXX/YY - Allows only that IP and its block

You can add your current IP automatically with one click.

Blacklist

Defines specific IPs that are blocked, even if they are on the whitelist.

Step 10: Finish Creation

1. Review all settings
2. Click "Create Project"
3. Wait a few seconds for creation

After Creation

You will receive:

• Project ID: Unique identifier of your project
• API Key: Key used to authenticate against the Zenifra API

Store the API Key safely! You will need it to manage your project through the API.

Next Steps

• How to Update an Image Automatically via GitHub
• Manage Projects
• Payment Settings

FAQ

Can I change the plan after creating the project?

It depends. If the payment model is Hourly, you can change the plan at any time. For monthly or yearly contracts, the change is only allowed at the end of the contracted period.

How do I update my project image?

If the project uses GitHub Repository as the source and auto-deploy is enabled, each push to the selected branch updates the instance automatically. If auto-deploy is disabled, publish manually from the console. If the project uses an OCI image, update the image in the console and publish the new version.

Can I change the pre-build, build, and start commands later?

Yes. In projects with source GitHub Repository, you can edit those commands after creation on the edit project screen.

Can I change the persistence directory later?

No. The directory chosen during creation for persistent storage, such as /data, cannot be changed later.

Can I have multiple projects?

Yes. There is no project limit per account. Each project is billed independently according to its settings.

How do I delete a project?

1. Open the specific project page
2. Click Delete
3. Confirm the action

Warning: This action is irreversible. All data and settings are permanently deleted.