How ForgeKit Works

The simple model behind local sites, servers, PHP versions, and databases.

Before you create your first server or site, it helps to understand three words you'll see everywhere in ForgeKit:

Binaries → Instances → Sites

Binaries

A binary is an installed version of a tool or runtime. Examples:

  • PHP 7.4.33
  • PHP 8.4.x
  • Apache 2.4.65
  • Nginx
  • MySQL 5.6.51
  • MariaDB

Binaries live in /bin.

By themselves, binaries don't run anything. They are installed versions, waiting to be used.

Instances

An instance is a configured, running server created from a binary. Examples:

  • Apache 2.4.65 + PHP 8.4 on port 8080
  • Apache 2.4.65 + PHP 7.4 on port 8081
  • MySQL 5.7 on port 3306
  • MySQL 5.6 on port 3307

Instances live in /instances. Each one has its own generated config, ports, logs, and runtime state.

A binary is installed. An instance runs.

Sites

A site is a local project. A site has:

  • a project folder
  • a local domain
  • a hosts file entry
  • a vhost entry inside the web-server instance it is routed to

A site is routed to one web-server instance.

One binary can have multiple instances

This is the part that trips people up most.

You may have only one Apache version installed:

Apache 2.4.65

But ForgeKit can create multiple Apache instances from that same binary:

/ForgeKit/instances/web/web-apache-2-4-65/
/ForgeKit/instances/web/web-apache-2-4-65-1/

Both instances use Apache 2.4.65, but they are separate configured servers. Each one can have its own ports, PHP version, vhost file, logs, and running process.

Example:

legacy.test  → Apache 2.4.65 instance #2 → PHP 7.4 → port 8081
modern.test  → Apache 2.4.65 instance #1 → PHP 8.4 → port 8080

Same Apache version does not mean same Apache instance.

If you manually check vhosts.conf, make sure you are looking inside the instance folder that the specific site is actually routed to, not just any folder that happens to have the right Apache version in its name.

Where logs fit in

Each instance keeps its own logs, and each PHP binary keeps a fallback log too. If a site's log looks empty, you may be checking the wrong one. See Where are logs stored? for the full breakdown.

Next