Wiki Help: How to Set Up a Domain for Localhost and Check Your Module License

 To open a local website using a domain name, map the name to an IP address in your hosts file and configure a VirtualHost on your web server. A local domain does not, by itself, activate a module license. Check the specific product’s rules for test installations and activation.

The example below uses Apache 2.4 installed directly on your computer and the address http://project.test. Docker, WSL, virtual machines, and other web servers require different network settings.

Localhost, a local domain, and a license: what is the difference?

Term What it means What it does not do
Localhost / 127.0.0.1 A connection to the current computer through its loopback interface Make your website accessible to an external service
Local domain A name that points to a local server on your computer Register a public domain
Hosts file A local mapping between a hostname and an IP address Change public DNS or configure Apache
VirtualHost Selects a website and directory for requests to a particular hostname and port Issue a license or create an HTTPS certificate
Module license The terms and mechanism for using a particular product Fix web server configuration

Check these in order: first confirm that the correct local copy opens, then investigate the module’s activation messages.

Do you need a separate license for localhost or a test domain?

There is no universal answer: check the specific module’s rules and your license details. Do not assume that a purchased license automatically covers an unlimited number of local or test installations.

Before configuration, ask the vendor:

  • whether local development and staging are supported;
  • whether an additional domain must be approved or a test key issued;
  • whether www, subdomains, ports, or other environment details affect activation;
  • whether a connection to an activation server is required;
  • how to transfer activation after changing the domain or server.

If the site opens but the module reports a license error, record the exact message, the module name and version, and the local site address. That is enough to start investigating; you do not need to share the full license key in a public message.

Which domain should you use for a local website?

This example uses project.test. The .test top-level domain is reserved for testing by RFC 2606. You still need to configure the name locally: using project.test does not start a server.

Avoid arbitrary domains in public zones such as .site, since they may belong to someone else. Do not override your live store’s address without a specific reason; doing so makes it easier to confuse test and production environments.

If testing requires a hostname specified by the vendor, agree on that name and its activation rules first.

Step 1. Add the local domain to your hosts file

Back up the file before editing. Open it with administrator privileges and preserve existing entries.

System Typical location
Windows C:WindowsSystem32driversetchosts
Linux /etc/hosts
macOS /etc/hosts

The Windows system directory can vary; the corresponding path is %WinDir%System32driversetchosts. Microsoft explains the file’s purpose in its hosts file guidance.

Add this line:

127.0.0.1 project.test

The hosts file contains only the IP address and hostname: do not include http://, a port number, or a page path. Save the file as hosts, without a .txt extension.

This change applies to the computer where you edited the file. Another laptop or a container needs its own configuration.

Step 2. Configure an Apache 2.4 VirtualHost

Locate Apache’s active configuration. Depending on the installation, this may be httpd.conf, an included virtual host file, or a configuration under sites-available. Make sure the file you create is actually included in the server configuration.

Example for the local directory /var/www/project/public:

<VirtualHost 127.0.0.1:80>     ServerName project.test     DocumentRoot "/var/www/project/public"      <Directory "/var/www/project/public">         Options -Indexes         AllowOverride None         Require local     </Directory> </VirtualHost>

Replace both paths with your website’s actual public directory. On Windows, this might be C:/sites/project/public. Not every project has a public directory: use the directory containing the website’s entry point.

ServerName sets the hostname, while DocumentRoot sets the directory. See Apache’s name-based virtual host documentation.

Require local is intended for local access; its rules are described in the mod_authz_host documentation. This example is not intended for public staging or access by colleagues over the network.

Check Listen. A VirtualHost does not make Apache listen on a port. For a dedicated local instance, you can use:

Listen 127.0.0.1:80

Do not add this alongside an existing Listen 80 without reviewing the active directives and removing overlaps. Changing Listen affects the entire server instance, so review its impact on other websites first. See Apache’s address and port configuration guide.

If your website uses .htaccess

In the minimal example above, AllowOverride None disables .htaccess processing. For a CMS that relies on routing rules, allow the necessary directives or move them into the VirtualHost configuration.

Rules using RewriteEngine and RewriteRule generally require mod_rewrite and permission for the FileInfo override category. If .htaccess contains other directives, review those separately. Do not switch to All simply to make an error disappear. See how Apache processes .htaccess files.

Avoid mixing the older Order allow,deny and Allow from all directives with modern Require directives. Apache advises against this combination in its 2.2-to-2.4 migration guide.

Step 3. Check the configuration and restart the server

Run commands for the Apache installation that actually serves your website.

On Debian/Ubuntu with the Apache package installed:

sudo apache2ctl configtest sudo apache2ctl -S

The first command checks syntax; the second displays the virtual host configuration. If the check succeeds, restart the local server:

sudo systemctl restart apache2

On Windows, from the directory containing your installation’s httpd.exe:

httpd.exe -t httpd.exe -S

After a successful check, restart Apache through your local environment’s control panel or service. On macOS, the method depends on the installed distribution; systemctl is not a universal macOS command.

The -t and -S options are documented in the official httpd reference.

Step 4. Confirm that you are opening the local copy

Open http://project.test and look for a clear sign that this is the test environment, such as a visible “Local copy” label. Use a separate database and disable jobs that send real messages, initiate payments, or synchronize with production systems.

To inspect the HTTP response, run:

curl -I http://project.test

To test the VirtualHost independently of the hosts file:

curl --noproxy "*" --resolve project.test:80:127.0.0.1 -I http://project.test

In Windows PowerShell, use curl.exe if necessary. The --resolve option sets the address for this request only, without changing the hosts file. --noproxy prevents a proxy from affecting the test. See the curl manual.

Not every application supports the HEAD requests sent by -I. If you receive 405, try a normal GET request by removing -I. A 200 response also does not, by itself, confirm module activation.

What should you check if the local domain does not work?

Symptom What to check first
Hostname cannot be resolved Hosts entry, accidental .txt extension, whether the file was saved, caches, and proxies
Connection refused Whether Apache is running and listening on the correct address and port
A different website opens ServerName, inclusion of the VirtualHost file, and the output of -S
403 Forbidden Directory configuration, directory read permissions, access rules, and Apache logs
Homepage works but other pages return 404 CMS routing, mod_rewrite, and .htaccess rules
Redirect to the production domain CMS base URL and redirects in configuration or plugins
Certificate error Whether the certificate matches the hostname and its issuer is trusted
Website works but the module reports an invalid license Test activation terms, domain details, and the exact error message

For HTTP 500, inspect the web server and application logs. This is a separate troubleshooting path; see our guide to fixing a 500 error.

How do you enable HTTPS for a local domain?

A hosts entry does not configure HTTPS. You need a certificate for project.test, trust in that certificate on your computer, and an HTTPS VirtualHost.

For development, mkcert can create locally trusted certificates, but it does not configure your web server for you. Do not share the local certificate authority’s private key, rootCA-key.pem, or commit it to a repository.

If the browser or application forces HTTPS, identify the redirect or HTTPS requirement first. Ignoring a browser warning is not a substitute for configuring the certificate correctly.

Why are webhooks not reaching localhost?

For an external service, localhost refers to its own environment, not your computer. A hosts entry on your PC does not make the address accessible to a CRM, payment provider, or marketplace.

Incoming requests may require a separate test environment with a reachable HTTPS address or a configured tunnel. Check the service’s requirements for callback URLs, request signatures, and test mode.

An outgoing API request from your local website and an incoming webhook travel in different directions. One working does not prove the other works. For the basics, see what API integration means.

CiFrame can help check your local website and integration

We can investigate whether the issue is in local domain configuration, the server, website settings, or module activation.

For your initial inquiry, send:

  • the CMS and module names and versions;
  • your operating system and local development environment;
  • the address you use to open the copy;
  • the exact error message or a screenshot without sensitive data;
  • your intended outcome: local testing, staging, or migration.

Contact info@ciframe.com. Once the task is clear, we will agree on the scope of the assessment and next steps. Licensing terms for a third-party product must be confirmed by its vendor.

Check my test environment

Frequently asked questions

Do I need to buy a domain for localhost?

You do not need public registration for a local name such as project.test configured through your hosts file. Requirements for an externally accessible test environment depend on how it is hosted.

Is changing the hosts file enough to activate a module license?

No. The hosts file changes the local hostname-to-IP mapping. Activation depends on the specific module’s mechanism and rules.

Do I need to change the production domain’s DNS?

Not for this project.test example. These changes are local and do not affect your production website’s public DNS.

Why does localhost work while project.test does not?

Check your hosts file, ServerName, and whether the VirtualHost configuration is loaded. A working default localhost page does not mean the server is configured for another hostname.

What if port 80 is already in use?

Identify the application using it. You can choose another available port for the local server, use the same port in Listen and VirtualHost, and open an address such as http://project.test:8080. Do not add the port to the hosts file.

Why does the example not work in Docker or WSL?

The server may run in a separate network environment. Check port publishing and addresses: 127.0.0.1 inside a container does not refer to the host computer. This example assumes Apache runs directly on the PC.

Can I work completely offline?

Local files and a database may work without external access, but license activation and integrations may require an internet connection. Check this separately for each module and service.

CiFrame Contacts
Free consultation
Take the first step

Start the evaluation and implementation process