How do you set up a local testing server?
=========================================

This article explains how to set up a simple local testing server on your machine, and the basics of how to use it.

|  |  |
| --- | --- |
| Prerequisites: | 
 You need to first know
 how the Internet works, and
 what a Web server is.
  |
| Objective: | You will learn how to set up a local testing server. |

Local files vs. remote files
----------------------------

Throughout most of the learning area, we tell you to just open your examples directly in a browser — this can be done by double-clicking the HTML file, dragging and dropping it into the browser window, or choosing *File* > *Open…* and navigating to the HTML file. There are many ways to achieve this.

If the web address path starts with `file://` followed by the path to the file on your local hard drive, a local file is being used. In contrast, if you view one of our examples hosted on GitHub (or an example on some other remote server), the web address will start with `http://` or `https://`, to show that the file has been received via HTTP.

The problem with testing local files
------------------------------------

Some examples won't run if you open them as local files. This can be due to a variety of reasons, the most likely being:

* **They feature asynchronous requests**. Some browsers (including Chrome) will not run async requests (see Fetching data from the server) if you just run the example from a local file. This is because of security restrictions (for more on web security, read Website security).
* **They feature a server-side language**. Server-side languages (such as PHP or Python) require a special server to interpret the code and deliver the results.
* **They include other files**. Browsers commonly treat requests to load resources using the `file://` schema as cross-origin requests.
 So if you load a local file that includes other local files, this may trigger a CORS error.
Running a simple local HTTP server
----------------------------------

To get around the problem of async requests, we need to test such examples by running them through a local web server.

### Using an extension in your code editor

If you only need HTML, CSS and JavaScript, and no server-side language, the easiest way may be to check for extensions in your code editor. As well as automating installation and set-up for your local HTTP server, they also integrate nicely with your code editors. Testing local files in an HTTP server may be one click away.

For VSCode, you can check the following free extension:

* `vscode-preview-server`. You can check it on its home page.
### Using Python

Another way to achieve this is to use Python's `http.server` module.

**Note:** Older versions of Python (up to version 2.7) provided a similar module named `SimpleHTTPServer`. If you are using Python 2.x, you can follow this guide by replacing all uses of `http.server` with `SimpleHTTPServer`. However, we recommend you use the latest version of Python.

To do this:

1. Install Python. If you are using Linux or macOS, it should be available on your system already. If you are a Windows user, you can get an installer from the Python homepage and follow the instructions to install it:
    * Go to python.org
    * Under the Download section, click the link for Python "3.xxx".
    * At the bottom of the page, click the *Windows Installer* link to download the installer file.
    * When it has downloaded, run it.
    * On the first installer page, make sure you check the "Add Python 3.xxx to PATH" checkbox.
    * Click *Install*, then click *Close* when the installation has finished.
2. Open your command prompt (Windows) / terminal (macOS/ Linux). To check if Python is installed, enter the following command:

```bash
python -V
# If the above fails, try:
python3 -V
# Or, if the "py" command is available, try:
py -V
```

3. This should return a version number. If this is OK, navigate to the directory that contains the website code you want to test, using the `cd` command.

```bash
# include the directory name to enter it, for example
cd Desktop
# use two dots to jump up one directory level if you need to
cd ..
```

4. Enter the command to start up the server in that directory:

```bash
# If Python version returned above is 3.X
# On Windows, try "python -m http.server" or "py -3 -m http.server"
python3 -m http.server
# If Python version returned above is 2.X
python -m SimpleHTTPServer
```

5. By default, this will run the contents of the directory on a local web server, on port 8000. You can go to this server by going to the URL `localhost:8000` in your web browser. Here you'll see the contents of the directory listed — click the HTML file you want to run.

**Note:** If you already have something running on port 8000, you can choose another port by running the server command followed by an alternative port number, e.g. `python3 -m http.server 7800` (Python 3.x) or `python -m SimpleHTTPServer 7800` (Python 2.x). You can then access your content at `localhost:7800`.

Running server-side languages locally
-------------------------------------

Python's `http.server` (or `SimpleHTTPServer` for Python 2) module is useful, but it is merely a *static* file server; it doesn't know how to run code written in languages such as Python, PHP or JavaScript. To handle them, you'll need something more — exactly what you'll need depends on the server-side language you are trying to run. Here are a few examples:

* To run Python server-side code, you'll need to use a Python web framework. There are many popular Python web frameworks, such as Django (a guide is available), Flask, and Pyramid.
* To run Node.js (JavaScript) server-side code, you'll need to use raw node or a framework built on top of it. Express is a good choice — see Express Web Framework (Node.js/JavaScript).
* To run PHP server-side code, launch PHP's built-in development server:

```bash
cd path/to/your/php/code
php -S localhost:8000
```