IQVForge

English | Türkçe

IQVForge is IQVizyon's self-hosted software development platform. It provides Git hosting, code review, issue tracking, project planning, package registries, releases, and continuous integration in a single deployable service.

Product principles

• Operated and maintained as an IQVizyon product
• Designed for private, reliable, self-hosted deployments
• Built with the IQVizyon design system, tokens, and frontend iconography
• Compatible with established Git clients and development workflows
• Maintained with production-grade security, testing, and deployment practices

Local deployment

Requirements

• Docker Engine with Docker Compose v2 on Linux
• Docker Desktop using Linux containers on Windows or macOS
• At least 4 GB of memory available to Docker for the initial image build

On Windows, Docker Desktop's WSL 2 backend is recommended.

Application data is stored in a Docker-managed volume, so the repository may be cloned on either NTFS or the WSL filesystem without exposing Forgejo's Linux UID and GID permissions to the Windows host.

Deployment configuration

IQVForge runtime addresses can be configured using environment variables.

The repository contains an .env.example file as a configuration template.

The actual .env file is environment-specific and must not be committed to Git.

Create the local environment file

On Windows:

Copy-Item .env.example .env

On Linux or macOS:

cp .env.example .env

Then edit .env according to the deployment environment.

Default values

If no custom values are supplied, docker-compose.yml uses the following defaults:

TZ=Europe/Istanbul

IQVFORGE_DOMAIN=localhost
IQVFORGE_ROOT_URL=http://localhost:3000/

IQVFORGE_SSH_DOMAIN=localhost
IQVFORGE_SSH_PORT=2222

These defaults are suitable for access from the same machine only.

Local-only configuration

For a development environment accessed only from the host machine:

TZ=Europe/Istanbul

IQVFORGE_DOMAIN=localhost
IQVFORGE_ROOT_URL=http://localhost:3000/

IQVFORGE_SSH_DOMAIN=localhost
IQVFORGE_SSH_PORT=2222

The application will then be available at:

http://localhost:3000

Git SSH access:

ssh://git@localhost:2222

LAN / IP configuration

When IQVForge must be accessed by other devices or an external Forgejo Runner, use an IP address reachable from those systems.

Example:

TZ=Europe/Istanbul

IQVFORGE_DOMAIN=192.168.10.45
IQVFORGE_ROOT_URL=http://192.168.10.45:3000/

IQVFORGE_SSH_DOMAIN=192.168.10.45
IQVFORGE_SSH_PORT=2222

The application will then advertise:

http://192.168.10.45:3000/

and Git SSH clone URLs will use:

ssh://git@192.168.10.45:2222/

The IP address above is only an example. Use the current IP address assigned to the IQVForge host.

DNS / production configuration

For permanent environments, using a stable DNS name is recommended instead of a dynamic IP address.

Example:

TZ=Europe/Istanbul

IQVFORGE_DOMAIN=forge.example.com
IQVFORGE_ROOT_URL=https://forge.example.com/

IQVFORGE_SSH_DOMAIN=forge.example.com
IQVFORGE_SSH_PORT=2222

When a reverse proxy terminates HTTPS, IQVFORGE_ROOT_URL must contain the externally accessible HTTPS address.

For example:

https://forge.example.com/

The underlying Docker service may continue listening on port 3000 while the reverse proxy exposes the application on standard HTTPS port 443.

Environment variables

Variable	Description	Default
TZ	Application timezone	Europe/Istanbul
IQVFORGE_DOMAIN	Hostname or IP address advertised by IQVForge	localhost
IQVFORGE_ROOT_URL	Complete external Web/API URL	http://localhost:3000/
IQVFORGE_SSH_DOMAIN	Hostname or IP advertised in Git SSH clone URLs	localhost
IQVFORGE_SSH_PORT	External Git SSH port	2222

ROOT_URL requirement

IQVFORGE_ROOT_URL must be reachable by every system that needs to communicate with IQVForge.

This includes:

• User web browsers
• Git clients
• API clients
• Forgejo Runner hosts
• Forgejo Actions job containers
• Artifact upload and download actions

Using localhost as ROOT_URL is only suitable when all access happens from the IQVForge host itself.

For example, inside a CI job container:

localhost

refers to the CI job container itself, not the IQVForge server.

For distributed Runner environments, configure IQVFORGE_ROOT_URL using a reachable LAN IP address or, preferably, a stable DNS name.

Docker port mapping

The default Docker Compose configuration exposes:

ports:
  - "3000:3000"
  - "2222:22"

This means:

Service	Host port	Container port
IQVForge Web / API	3000	3000
Git SSH	2222	22

The effective configuration can be inspected with:

docker compose config

Running containers and published ports can be inspected with:

docker compose ps

or:

docker port iqvforge

Start IQVForge

Build and start the application from the repository root:

docker compose up --build -d

Check that the container is running:

docker compose ps
docker compose logs --tail 100 iqvforge

When using the default configuration, open:

http://localhost:3000

When using a custom .env, open the URL configured in:

IQVFORGE_ROOT_URL

Complete the initial configuration.

Keep the default SQLite path:

/data/gitea/gitea.db

A syntactically valid company email address can be used for the administrator account. E-mail delivery is not required unless SMTP features are enabled.

Configuration verification

Before starting or recreating the container, verify the resolved Docker Compose configuration:

docker compose config

For example, a LAN deployment may resolve to:

FORGEJO__server__DOMAIN: 192.168.10.45
FORGEJO__server__ROOT_URL: http://192.168.10.45:3000/
FORGEJO__server__SSH_DOMAIN: 192.168.10.45
FORGEJO__server__SSH_PORT: "2222"

After IQVForge starts, inspect the startup log:

docker compose logs --tail 100 iqvforge

The log should report the configured application URL rather than an unintended localhost address.

Timezone

The default timezone is:

Europe/Istanbul

It can be configured in .env:

TZ=Europe/Istanbul

For temporary shell-based overrides, the environment variable may also be set before running Docker Compose.

Linux or macOS:

TZ=UTC docker compose up --build -d

PowerShell:

$env:TZ = "UTC"
docker compose up --build -d

Environment file security

The real .env file is local deployment configuration and must not be committed to the repository.

The repository should contain:

.env.example

but not:

.env

The .gitignore file therefore contains:

/.env

Before committing deployment changes, verify:

git status

The .env file must not appear in the Git change list.

Persistent data

Forgejo configuration, the SQLite database, repositories, attachments, Actions data, package data, and SSH state are stored in the Docker-managed iqvforge-data volume declared by docker-compose.yml.

Docker Compose applies a project prefix to the physical volume name so separate checkouts do not share data accidentally.

Stopping or rebuilding the containers preserves the volume:

docker compose down
docker compose up --build -d

Do not run:

docker compose down -v

unless you intentionally want to permanently delete the IQVForge Docker data volume.

Migrating an existing bind-mounted installation

Older checkouts may store data in the local:

./iqvforge-data

directory.

If that directory contains an existing installation, migrate it before starting the updated Compose configuration.

First stop the old container and create the new named volume without starting IQVForge:

docker compose down
docker compose create

Confirm that ./iqvforge-data contains the expected:

gitea
git
ssh

directories.

Then copy the existing installation into the empty named volume:

docker compose run --rm --user root --entrypoint sh -v ./iqvforge-data:/source:ro iqvforge -c 'test -z "$(ls -A /data)" || { echo "Target volume is not empty" >&2; exit 1; }; cp -a /source/. /data/; chown -R 1000:1000 /data/gitea /data/git'

Start IQVForge:

docker compose up -d

Verify the logs:

docker compose logs --tail 100 iqvforge

Verify the existing:

• Administrator account
• User accounts
• Repositories
• Issues
• Pull requests
• Releases
• SSH keys

before archiving the old host directory.

The migration command refuses to merge data into a non-empty target volume. This prevents accidental overwrites.

Keep the original ./iqvforge-data directory until the migrated installation has been verified.

Forgejo Actions and Runner connectivity

IQVForge supports Forgejo Actions workflows stored under:

.forgejo/workflows/

For example:

.forgejo/workflows/ci.yml

A Forgejo Runner may run on another server or inside a separate container environment.

The Runner and its job containers must be able to resolve and connect to the address configured as:

IQVFORGE_ROOT_URL

For example, this configuration:

IQVFORGE_ROOT_URL=http://localhost:3000/

is not suitable for a Runner operating on another machine or in an isolated job container.

Use a reachable address instead:

IQVFORGE_ROOT_URL=http://192.168.10.45:3000/

or preferably:

IQVFORGE_ROOT_URL=https://forge.example.com/

This is required for features including:

• Workflow communication
• Artifact upload
• Artifact download
• API requests generated by Actions
• Server-generated links

Health check

After startup, IQVForge health can be checked with:

/api/healthz

For a default local deployment:

curl http://localhost:3000/api/healthz

For a configured LAN deployment:

curl http://192.168.10.45:3000/api/healthz

A healthy installed instance should report a passing status for the application and its required internal services.

Troubleshooting

Startup logs

Inspect startup and installation errors with:

docker compose logs --tail 250 iqvforge

Persistent storage permissions

Confirm the application user can write its persistent paths:

docker compose exec --user git iqvforge sh -c 'id; test -w /data/gitea && echo writable || echo not-writable; test -w /data/gitea/conf/app.ini && echo config-writable || echo config-not-writable'

If installation reports permission denied, verify that the service uses the named iqvforge-data volume and does not still have a local:

./iqvforge-data:/data

override.

On SELinux-enabled Linux hosts, named volumes also avoid the relabeling requirements associated with bind mounts.

Port conflicts

If port 3000 or 2222 is already in use, inspect the current mappings:

docker compose ps
docker port iqvforge

Then stop the conflicting service or change the host side of the corresponding mapping in docker-compose.yml.

ROOT_URL and Actions artifact errors

If an Actions job reports connection errors similar to:

connect ECONNREFUSED 127.0.0.1:3000

verify that IQVForge is not advertising:

http://localhost:3000/

to external Runner job containers.

Check the effective configuration:

docker compose config

and verify:

FORGEJO__server__ROOT_URL

uses an address reachable from the Runner environment.

After changing .env, recreate the IQVForge container so the new environment is applied:

docker compose up -d

The persistent data volume is preserved during this operation.

Design system

IQVForge uses the IQV design system for its visual tokens and frontend icon system.

Upstream and license

IQVForge is a modified distribution based on Forgejo and Gitea.

IQVizyon maintains the product-specific branding, interface, integration, and deployment changes in this repository.

The software remains distributed under the GNU General Public License version 3 or later.

Existing copyright and license notices in upstream-derived source files are retained.