AMPS is used for a wide variety of applications, from extreme low-latency applications with a latency budget of less than a millisecond roundtrip to applications that aggregate millions of fast changing records that intentionally conflate updates to reduce load on a user interface. All of these applications have one thing in common, though: AMPS runs on x64 Linux, so application developers need to have access to a Linux installation to develop against AMPS.

For sites (or developers) typically focused on Windows development, this can sometimes make it seem more difficult than necessary to get started with AMPS. Installing a virtualization product like VirtualBox or VMWare works well, but involves installing the virtualization software, choosing and manually installing a Linux distribution, and then dealing with what is effectively an entirely separate desktop and development system.

On recent builds of Windows 10, the process can now be just a few simple steps. These builds include Windows Subsystem for Linux 2 (WSL2), which runs a Linux kernel on Microsoft’s Hyper-V. It’s included as an optional feature of Windows 10 starting with the May 27, 2020 update (version 2004 / build 19041 and later). The Linux distributions are provided through the Windows Store, and are simple to download and install for people who don’t spend a lot of time managing Linux systems.

If you don’t already have an existing setup for running a Linux server on your windows system, WSL2 is a great solution. There’s no need to have a separate development system or to set up separate Virtual Machine software – you can do everything you need using the WSL2 system provided with Windows.

The advantages of running AMPS on WSL2 are the same as the general advantages of WSL2:

• Good performance
• An environment that is, effectively, identical to a native Linux install for Linux applications
• Tight integration with the Windows environment
• Easy installation and setup (especially as compared with installing Linux on a VM)

AMPS runs perfectly well on WSL2. All unit and integration tests pass on WSL2 (stress and long-haul-testing suites require several systems with high-speed networking between them, so those aren’t really run on any development system). In fact, AMPS (and the development environment for AMPS) run well enough that several members of the 60East development team now use WSL2 as their main development environment when working on the AMPS server.

AMPS On Windows: Step by Step

To set up WSL2 and get AMPS running, follow these steps:

1. First, you need to make sure you’re running a version of Windows 10 that includes WSL2. As mentioned earlier, any version of Windows 10 more current than version 2004 / build 19041 will work. If you’re using an older version of Windows 10, you’ll need to allow a Windows feature update to get WSL2 running.

2. Install WSL2. There are instructions in the Microsoft documentation for Installing WSL. In most cases, this boils down to the following command in an Administrator Powershell:

   PS C:\Users\yourname> wsl --install
   

   This installs an Ubuntu distribution by default. If you prefer to use a different distribution, the Installing WSL instructions include information on installing a different distribution. (In our experience, Ubuntu works quite well as a development environment.)

   To use WSL2 after installing it, you will need to restart your system.

3. Optionally (but strongly recommended), you can set up other aspects of your development environment. Among other things, this lets you set a user name and password for the user that shells run under, and so on. You can find full WSL Environment Setup instructions in the Microsoft documentation.

4. Install AMPS. This is a matter of downloading the latest release from the AMPS release page and then extracting it. Start the bash shell for your Linux distribution (if you’ve installed Ubuntu, you can run this by starting Ubuntu from the start menu) or Windows Terminal. Navigate to your home directory, then download and extract AMPS. You can use any current version of AMPS.

   For example, to install AMPS 5.3.3.30, you would run commands like:

   Navigate to your home directory:

   $ cd ~
   

   Download the AMPS binary:

   $ wget https://devnull.crankuptheamps.com/releases/amps/5.3.3.30/AMPS-5.3.3.30-Release-Linux.tar.gz
   

   Extract the AMPS binary:

   $ tar -zxf AMPS-5.3.3.30-Release-Linux.tar.gz
   

5. Start AMPS. To start AMPS, just run the AMPS binary with a valid configuration file. To use the minimal configuration template included with the server, first have the server produce the configuration file and then start AMPS.

   In a bash shell or Windows terminal window, navigate to your home directory:

   $ cd ~
   

   Have the server produce the minimal sample configuration and save it to a file:

   $ ./AMPS-5.3.3.30-Release-Linux/bin/ampServer --sample-config > minimal.xml
   

   And then run AMPS, using that file as the AMPS configuration:

   $ ./AMPS-5.3.3.30-Release-Linux/bin/ampServer minimal.xml
   

   Depending on your Windows settings, you may get a warning from Windows firewall when AMPS starts. Check the appropriate boxes for the permissions you want AMPS to have.

That’s all it takes to get a minimal AMPS configuration up and running!

Tips for WSL2

You now have a running AMPS instance on your Windows system! If you’ve used the sample configuration, you can now open a browser on your Windows desktop and navigate to http://localhost:8085/ to see the Galvanometer for the instance.

A few useful tips:

• Typically, AMPS will issue a few warnings on startup. The exact warnings depend on the distribution and version you chose for WSL2. The most common warning is that AMPS can’t determine the layout of the system for NUMA tuning. In a production system, it would be important to understand these warnings and determine if they need to be resolved. Since the WSL2 setup here is intended for interactive development rather than production, it’s generally alright to ignore these warnings and deal with any issues if they emerge.

• For developing applications that will run on Linux, Visual Studio Code works well as a development environment. There’s an extension (the Remote - WSL extension) that provides excellent integration with the WSL2 environment.

• If, at any point, you want to show the current directory in a File Explorer window, you can type explorer.exe . into the bash shell, and Windows will open that path in File Explorer. (This is also a convenient way to get the file path for things like uploading files from or saving files to the Linux environment.)

• The WSL2 environment can host multiple AMPS instances, if necessary, to do development with a basic replication and failover scenario. (Of course, the more CPU-intensive processes you have running on the development system, the fewer resources are devoted to each process.)

• There is a known issue with IPv4 over IPv6 networking in current builds of WSL2 (see the github issue ). This means that, if you are using a recent preview of AMPS and the Transport configuration for the server provides an InetAddr that only uses a port number (for example, <InetAddr>9007</InetAddr>, as the minimal sample does) then simply connecting to AMPS from Windows processes using localhost won’t work. To connect to the AMPS server from the Windows side in this case, you have a few different options:

  1. You can connect to AMPS over IPv6 (if you are using a current client library and a current preview version of AMPS). Rather than connecting using a string like tcp://locahost:9007/amps/json, connect over IPv6 using a string like tcp://[::1]:9007/amps/json.

  2. Explicitly bind the Transport to IPv4. To do this, you would change the InetAddr in the configuration to a value along the lines of <InetAddr>0.0.0.0:9007</InetAddr>, which will tell the AMPS server to listen on all IPv4 interfaces (but no IPv6 interfaces).

  3. Find the ethernet address of the WSL2 interface (using ip addr | grep eth0in the WSL2 bash shell) and connect using that IP rather than localhost. Unfortunately, this address may change if the system is restarted.

  For local development purposes, we generally take approach 1 or approach 2, since this can be set up once (in the application configuration file or the AMPS server configuration file) and then stay working.

Crank Up Your Windows!

Those of us who run Windows systems at 60East are big fans of WSL2. Although virtual machines work well, the ease of use and simple Windows integration make WSL2 enjoyable to work with. We hope that you’ll enjoy it too!

Have more tips or tricks when using WSL2? Drop us a line, or let us know in the comments!