Accessing Settings

To operate these settings through the API, grant the minimum scope for each action on project:<project-id>:

An owner has full access in a user session. assistant, member, and organization API Keys need the specific grant.

1. In the sidebar, click Projects
2. Find and click on the project name you want to edit
3. On the project page, click the Edit button

Note: Whitelist and blacklist are exclusive to HTTP projects. Databases do not offer whitelist or blacklist.

Available Settings

Project Name

The project name can be changed at any time.

Rules:

• Minimum: 6 characters
• Maximum: 32 characters
• Only lowercase letters, numbers, and hyphens

Note: Changing the name does not affect the existing subdomain.

Zenifra subdomain

When a project is created or made public, it receives a Zenifra subdomain without using the project ID. The address is based on the project name and may receive a random suffix when that name is already in use.

When the plan allows customization (Premium and above), change the subdomain in the Primary domain section and click Save primary domain. The requested subdomain must contain 3–54 characters with lowercase letters, numbers, and internal hyphens. Private projects have no public domain.

Project Description

The project description can be changed at any time.

Characteristics:

• Optional field to describe the project purpose
• Helps identify and organize your projects
• Can include information such as technology used, client, or purpose

Project Image

The OCI image used by the project can be updated.

How to update:

1. In the image section, enter the new image in the format:

   docker.io/nginx:alpine

Limitations:

• Cannot change the image authentication type (public/private)
• Private image must remain private
• Public image must remain public

Tip: To automatically update the image via GitHub Actions, check our automatic deployment tutorial.

Git repository and build commands

Forgejo projects have the Git repository section, which lets you change the repository or branch, adjust the runtime (Node.js or Python) and version, edit the Start Command, Pre-build Command, Build Command, and Root directory, and disconnect the repository. GitHub projects created in the console show the GitHub deployment card and the GitHub commands section (Start command, Pre-build command, Build command, and Root directory); runtime and branch cannot be changed in the console. In GitHub projects, saving new commands or a new root directory triggers a new build; in Forgejo projects, the change applies from the next build.

When this is useful:

• Adjust the build flow after changing the framework or repository structure
• Fix installation commands before a new deployment
• Change the startup command without recreating the project
• Point the build to another repository folder, as in monorepos

Command examples:

pre-build: npm install
build: npm run build
start: npm run start

pre-build is optional, build is also optional, and start remains required. Simpler projects can work with start only.

Root directory is the repository folder where install, build, and start run. Use . for the root or a relative path such as backend or apps/api, without .. and without a leading slash. If the folder does not exist on the branch, the build fails with the message "The configured root directory does not exist in the repository.". See Root directory and monorepos.

Note: This option applies to projects whose source is a Git repository. Projects published from an OCI image do not use these commands on this screen.

Project Exposure

HTTP projects can be changed between Public and Private even after creation.

How to change it:

1. On the project edit page, find the Exposure section
2. Select Public - exposes route and domain or Private - no public route
3. Click Save Exposure
4. Confirm the action in the modal

Effects:

• Public: creates or restores the public route and project domain
• Private: removes the public route, Zenifra subdomain, and custom domains
• Custom domains and IP access rules are editable only while the project is public

Use Private for automations, admin apps, and routines that do not need to receive internet traffic. For tasks that run at set times, use a Scheduled Job.

Environment Variables (ENVs)

Environment variables can be added, edited, or removed.

Characteristics:

• Limit of 50 ENVs per project
• Instances are automatically restarted when changing ENVs
• Use ENVs for sensitive configurations like API keys and database passwords

ENV examples:

DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=your-api-key-here
NODE_ENV=production

Note: In addition to the ENVs you define, Zenifra can also inject operational variables automatically, such as ZENIFRA_INSTANCE_VERSION, which is useful for distinguishing versions in logs and troubleshooting.

Network Access

The Network access section is available from the Premium Plus plan and only for public projects. Turn on Enable IP access control, fill in the lists, and click Save network access. If the plan does not include the feature, the lists are ignored.

Whitelist (Allow List)

The Inbound allowlist defines which IP addresses can access the project.

Characteristics:

• Non-listed IPs will be blocked
• CIDR format: 192.168.1.0/24 or 10.0.0.1/32
• Maximum of 10 entries in the whitelist

How to add an IP: Enter the CIDR and a Description and click Add. (When creating the project, the Add Current IP button includes your address automatically.)

CIDR format:

• 0.0.0.0/0 - Allows all IPs
• XXX.XXX.XXX.XXX/32 - Specific IP
• XXX.XXX.XXX.XXX/YY - IP block

Note: Changing the whitelist does not restart instances.

Blacklist (Block List)

The Inbound blocklist defines IPs that will be blocked even if they are on the whitelist.

Characteristics:

• Blocked IPs will not have access to the project
• Useful for blocking malicious IPs
• Maximum of 10 entries in the blacklist

Note: Changing the blacklist does not restart instances.

Number of Instances

You can increase or decrease the number of project instances.

Limits:

• Minimum: 1 instance
• Maximum: depends on the plan's available capacity; when there is no capacity, the change is rejected
• Free plan: at most 2 instances in total per organization
• Instances cannot be changed while the project is paused
• With auto-scaling enabled, disable it to change instances manually

For traffic peaks: Use auto-scaling (paid plans), which adjusts instances between a minimum and a maximum based on CPU and memory.

Impact:

• More instances = greater processing capacity
• More instances = higher cost
• Traffic is distributed among instances

Storage, plan, and contract

• Storage: increases project storage; available only for hourly projects and cannot be reduced. See Storage.
• Plan: available only for hourly projects. Switching from or to the Free plan is not allowed.
• Contract: for monthly or yearly contracts, shows the payment mode, end date, and automatic renewal.

Health check and alerts

• Application healthcheck (Premium and above): checks a path, such as /health, every 60 seconds and lists failures from the last 30 days. See Ports and health checks.
• Email alerts: notifies you when the application restarts unexpectedly or when an instance uses 80% or more CPU or memory (at most one email per alert type per hour).

Project Actions

The actions are on the project page.

Pause the Project

When you click Pause and confirm with Pause project:

• Instances are stopped
• Ephemeral storage is deleted
• The project cannot be accessed
• For hourly projects, compute billing stops; additional persistent storage is still billed

When to use:

• When you don't need the application temporarily
• To save costs on hourly projects

Resume the Project

When you click Resume on a paused project:

• Instances are started again
• Ephemeral storage is recreated
• The project becomes accessible again
• Billing resumes (for hourly projects)
• If the organization is blocked due to outstanding amounts, resuming is refused until it is settled

Disable Automatic Renewal

Only for monthly or annual contract projects

In this case, the correct behavior is to prevent automatic contract renewal:

• the project remains active until the end of the contracted period
• after expiration, the contract is not renewed
• the flow is handled in the Contract section of the project edit page (Save automatic renewal)

Note: For hourly payment projects, this option is not available. Use Pause to stop compute billing.

Delete the Project

Click Delete on the project page and confirm. Deletion is permanent and irreversible.

What happens:

• All instances are removed
• All project data is deleted
• Storage is freed
• Hourly usage is closed and billed up to the moment of deletion

Next Steps

• Project Metrics and Insights
• How to Create a Project
• Payment Settings

FAQ

Can I change the project plan?

Yes, if the payment model is hourly: the plan can be changed at any time, except from or to the Free plan. Projects on a monthly or yearly contract cannot change plans.

Does changing ENVs cause downtime?

No. Instances are replaced to apply the new variables, and the previous instance keeps serving while the new one starts; see How a new version goes live. Variables used during the build, such as VITE_* and NEXT_PUBLIC_*, only change in the code after a New build.

Can I restore a deleted project?

No. Deletion is permanent. Make sure to backup your data before deleting.

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

Yes. In projects whose source is a Git repository (GitHub or Forgejo), these commands and the Root directory can be edited after project creation. In GitHub projects, saving the change starts a new build; in Forgejo projects, it applies from the next build.

Can I change the persistence directory later?

No. The path defined during project creation for persistent storage remains fixed after the project is created.

Does Zenifra inject any ENV automatically?

Yes. One example is ZENIFRA_INSTANCE_VERSION, which identifies the deployed instance version and can be used in your code to distinguish logs and releases.

What happens to data when stopping the project?

• Persistent data: Kept
• Ephemeral data: Deleted

We recommend using persistent storage for important data.