Project configuration

Project configuration in Zenifra defines how your application is published, executed, and exposed on the internet. This page is a central overview of the main settings available in the console, focused on rules, practical decisions, and the most important limits.

For step-by-step instructions, also see:

What project configuration includes

In the current Zenifra flow, project configuration can include:

project identity, such as name and description
publishing source, such as GitHub Repository or OCI Image
build and startup parameters for GitHub-based projects
environment variables and operational secrets
subdomain and custom domains
IP-based network access rules
operational capacity, such as instances and storage

These options are centered in the console and help define how the application is deployed, updated, and maintained.

What is usually defined at creation time and what can change later

Some choices are made during project creation, while others also appear again on the edit screen.

Area	Defined during creation	Can be adjusted later
Name and description	Yes	Yes
Project source	Yes	Check the current flow before assuming source switching
GitHub branch and commands	Yes, for GitHub projects	Yes
Environment variables	Yes	Yes
Custom domains	Yes	Yes
Instances	Yes	Yes
Storage	Yes	Capacity may vary depending on the plan; persisted directory rules need attention

Note: Not every setting follows the same editing rule. When a choice affects build, restart, persistence, or billing, validate the expected behavior on the project edit screen.

Choosing the project source

When creating an HTTP project, Zenifra mainly works with two source types.

GitHub Repository

This option is a good fit when you want deployment tied to source code. In this mode, the console can expose settings such as:

repository owner and repository name
branch
runtime and runtime version
auto-deploy
pre-build, build, and start commands

This model is useful for applications that evolve frequently and need a deployment flow closely tied to development.

If your project uses GitHub as the source, also see how to connect GitHub to Zenifra.

OCI Image

This option is a better fit when you already have a ready image, want to control the artifact outside GitHub, or need to publish through a registry.

It usually makes more sense when:

the build pipeline already runs outside Zenifra
the image is produced by external CI
you want to promote immutable tagged versions

If you need to change the published image, use the flow described in how to change a project image.

Build and startup in GitHub projects

In GitHub-based projects, configuration goes beyond choosing a repository. The console can also expose parameters that directly affect build and startup.

Runtime and version

These fields help align the build environment with the stack used by the project. In Node.js or Python flows, for example, choosing the correct version can avoid differences between development and production.

Auto-deploy

When enabled, auto-deploy allows pushes to the configured branch to trigger new deployments. This reduces manual work, but also requires more discipline around branch stability.

`pre-build`, `build`, and `start` commands

These commands control important deployment stages such as dependency installation, compilation, and application startup. They are especially useful when:

the project changed frameworks
the default command does not fit the repository structure
the startup process must be adjusted without recreating the project

In the confirmed current flow, projects using GitHub as the source can edit these commands after creation in the project settings screen.

Environment variables and secrets

Environment variables centralize values that should not be hardcoded in the repository, such as:

DATABASE_URL
API_KEY
PORT
external API URLs

Best practices:

use the console to store sensitive secrets
do not commit tokens, passwords, or keys to the repository
separate operational variables from local development values
review names and values before saving, because changes may require instance restarts

Platform-injected variables

In addition to the variables you define in the console, Zenifra can also inject operational variables automatically into instances.

One important example is:

ZENIFRA_INSTANCE_VERSION: identifies the deployed instance version

You can use this variable in your code to:

distinguish logs between different versions
quickly identify which release is serving a request
help with troubleshooting during rollouts and updates

For practical examples, see the HTTP project creation guide.

Network, domains, and public exposure

Subdomain and custom domains

Depending on the plan, a project can use a Zenifra subdomain and also accept custom domains. This layer defines how users reach your application.

Custom domains make sense when you want to:

publish with your company identity
separate environments by host
use a more stable endpoint for integrations

Whitelist and blacklist

For scenarios that require access control, Zenifra can also expose IP lists in CIDR format.

the whitelist defines who can enter
the blacklist blocks specific IPs

This is useful for internal environments, admin panels, restricted APIs, or staging phases.

Scale and operations

Instances

The number of instances affects capacity, availability, and cost. In general:

fewer instances simplify test environments
more instances increase capacity and redundancy

In confirmed edit flows from the console, instances are part of the project's operational settings.

Application port

The port tells Zenifra where HTTP/HTTPS traffic should be routed inside the container. It must match the port your application actually listens on.

Even when the detailed instructions live in the creation flow, this should still be treated as a critical part of the initial project configuration.

Persistent storage

Storage defines whether specific data inside the container should survive restarts and new executions.

When to use it

Persistent storage makes sense when the application needs to:

keep uploads
keep generated artifacts
preserve files used across restarts

A common use case is using /data to store temporary work files, imports, reports, or generated PDFs that may be deleted after use, but should not disappear in the middle of operations.

What to watch

configured capacity should match expected data volume
the persisted path should be chosen carefully
not every storage change follows the same rule across plans and billing models

If your flow depends on persistence, review the details in the HTTP project creation guide.