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.
| 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.
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:
www, subdomains, ports, or other environment details affect activation;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.
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.
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.
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.
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.
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.
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.
| 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.
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.
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.
We can investigate whether the issue is in local domain configuration, the server, website settings, or module activation.
For your initial inquiry, send:
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.
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.
No. The hosts file changes the local hostname-to-IP mapping. Activation depends on the specific module’s mechanism and rules.
Not for this project.test example. These changes are local and do not affect your production website’s public DNS.
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.
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.
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.
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.
