Help getting started - Achieve HTTP/S

This guide teaches the basics of setting up and running the Achieve HTTP and HTTPS server. It is written to help everyone who needs help - including complete beginners. If you have no previous experience running a server, start at the beginning and complete each step in sequence. Go as far as you need to achieve the results that you need.

CONTENTS

Brief Introduction to HTTP

HTTP stands for Hypertext Transfer Protocol. An internationally accepted standard exists that provides details on the interaction of "clients" (such as web browsers) and HTTP servers via the Internet.

Browsers and HTTP servers are constructed based on the standard; use the same protocol. This is why a variety of browsers, whether from Google or Mozzilla (Firefox), for example, can exchange information with HTTP servers all over the world.

HTTP is a core feature of the World Wide Web. If you have used a web browser, you already have some understanding of how it works. You enter an address in the browser's address bar or click on a link. A request is sent and you get something back - a response.

Install Achieve and run the first system test

If you have not already done so, install Achieve. Follow the instructions in the quick-start guide to the point that you can start the server (HTTP) and at least have an html page ready to be served. You can download this test html file once you know where to put it. Note that you can use setAppPath(), as explained in the quick-start guide to tell the Achieve server where your application files will be.

Once you have Achieve installed and started, open a web browser on the same computer. If you used default port 80, simply type "localhost" (without quotes) in the address bar. If you used a different port, then include that port number, for example; localhost:7777

localhost is a term that browsers and other software systems understand to mean this computer - i.e. the computer that you are currently using. It can only be used when a computer wants to address itself.

The web-page you put up should be displayed in the browser. If so, congratulations. The server is running and has served its first web page. The first test has been passed.

If this step fails, and you believe that you have done everything right, try a different port. Another application might be using the port you chose. This is often the case when using port 80, when you have Skype running for example.

Upon completion of this step, you already have a system that is sufficient for some development work. It can be very convinient to build your web applications on the machine that is running your server. You can use localhost to test as you build.

Allow access to other devices in your local area network

In this step, you will open your port through your computer's firewall. Other devices in your local area network will be able to send requests to your server.

Complete the step above before starting this one.

Your local area network typically consists of all devices that use the same router. If you are in a family home, one router typically serves all devices that are either wired into the router or using Wi-Fi.

Operating systems include "firewalls", a security feature that stops intrusions into your computer. Normally, whatever port you've chosen is blocked by your firewall. This means that requests sent from another device will not be able to reach your server. You need to "open" the port that you have chosen.

Specifically how to open ports through your firewall depends on what operating system you have. You may need to Google for instructions that are specific to your operating system. In Windows 10, click the start button and type "firewall". On my computer, I choose to check firewall status. Once in the firewall app, go to the advanced section (low down on the list on the left). Click "Rules for incoming trafic" on the left and then "New rule" on the right. That will start the guide that will take you through the steps needed to open one or more ports.

Follow the guide to open a TCP port with the port number you have chosen (and tested above). Allow connections of all types. Choose a convinient name like Achieve 7777 (with your port number in place of 7777). Write a description if you wish. Click to enter the rule. Now other computers in your local area network will be able to fetch the web page from your server.

But other computers cannot access the server using "localhost". Instead, they need to use your local IP address.

Click your start button and type cmd (Windows). Select cmd to open a command window. Type "ipconfig" without quotes and press Enter. Look for the "IPv4 Address". It is a set of numbers separated by periods. This address is called the local or internal IP address. It's the computer's address within the local area network. It's how your router addresses each device. These internal addresses are never seen outside of the local area network.

To test the server from another local device, use the local IP address in place of "localhost". For example, if your IPv4 Address (local IP address) is 192.168.1.8 and the port is 7777, put the following in the browser's address window: 192.168.1.8:7777

Local IP addresses tend to be quite stable in daily operation, but they can change. If you install a new router or reset your router to original factory settings, routers can reissue local IP addresses. If that happens, simply use ipconfig again to get the new address.

The browser should display the web page.

Access from the World Wide Web

In this step you will forward your port from your router. Other computers on the World Wide Web - anywhere in the world, will be able to send requests to your server.

Complete the step above before starting this one.

To grant access to the WWW, you need to let your router know which computer is using a chosen port. Log into your router and find the page used for port forwarding. Interfaces installed in routers can be designed differently. In my ASUS router, I go to Advanced Settings -> WAN and then click on the Virtual Server / Port Forwarding tab. Google or consult documentation for your particular router if Port Forwarding is difficult to find.

When you find the right page, add the port that you chose for running Achieve to the list. Once again, the protocol is TCP. The "External Port" (ASUS) is the port you have chosen to use. You also need to enter the Internal (local) IP address (explained above) of the computer that is running Achieve. Give the entry a convinient name such as Achieve 7777; using whatever port you've chosen.

When a request comes from the Internet, it first arrives at your router. Based on the port number, your router will now be able to forward the message to the right computer within your local area network. Now we just need a way for the outsiders to send things to your router.

In the address bar of your web browser, type "what's my ip". Either immediately at the top of the search listing or by clicking on one of the listings, you will get a set of numbers in the following form: 12.345.678.910. This is your External IP address. It's what the Internet uses to find your router.

To test the server to see if this works, use the External IP address and port as the address in the same way that you used the Internal (local) IP address above. For example, if your External IP address is 12.345.678.910 and the port is 7777, put the following in the browser address window: 12.345.678.910:7777

This address should work from anywhere in the world.

Your External IP address is not permanent. If you have a power outage or intentionally restart your router, you will typically be issued another address. The section on Domain names below also includes information on how to use a (free) domain name that will continue to work even when your External IP address changes. ("Dynamic DNS service")

Summary: Request-Response

If you are a beginner, this is a nice place to stop and reflect on the process that has been described.

When a web browser (generally known as a "client") processes the address that you enter in the address bar, it is initiating a "request" for a particular "resource" (such as an HTML page) or output from a program - in either case on some computer somewhere in the world that is running a server. The External IP address is the address used by the Internet to deliver the request to a particular router. Based on the port number, the router forwards the request to the computer that is running the server; using that computer's Internal (local) IP address. The server software has been configured to "listen" for messages coming to a particular port. When starting Achieve, you specify the port number in your start-up program as an argument to the listen() method. Achieve will then listen for messages on that port.

The story isn't quite complete yet. The addressing system is not only designed to find your server from anywhere in the world. The server must find the particular resource that has been requested. Based on the above, you have seen that if an HTML file is in the directory that you have chosen when setting up achieve, then the server finds and returns the HTML page using just IP addresses and port. But what if you have several projects going and decide to put each one in a separate subdirectory?

Let's say that the application directory that you have given to Achieve is c:/myapps. (using the setAppPath() method) And you create your first project in c:/myapps/project1. Based on the address to the server in the example above, the web address of project1 directory is 12.345.678.910:7777/project1.

Now let's say that your resource file is not given a default name (index.html, index.htm, and index.js will be found without specific mention of them in the resource address.) Let's say you want an HTML page named page1.htm. The address is 12.345.678.910:7777/project1/page1.htm

Adding subdirectly names applies to other resources as well, but you do not always need to specify the complete address. Once you have entered the complete address of an HTML page in the browser, the browser understands where you are starting - in this example; the 12.345.678.910:7777/project1/ directory. When your HTML page requests other resources, such as JavaScript and CSS files, you can use their address relative to that. For example, page1.htm can request main.css in the c:/myapps/project1/css directory as "css/main.css".

The server sends back a "response". In these examples, the response contains the HTML or CSS files that were requested. As explained in the introduction, this is how HTTP works: request-response. The request includes information about the client's IP address and port. The roles now become reversed. The server is the sender and the browser is the receiver. But browser users do not need to perform any special configuration steps to receive the response. The browser and router save information when the request is made, enabling the response to be directed back to the right computer and into the right browser tab.

Domain names

This section discusses domain names and alternatives for obtaining them.

Domain names, such as google.com, are registered in the Internet's Domain Name System (DNS). This involves a list, found on many "domain name servers" around the world that match registered domain names with External IP addresses. If you have registered myfrog.org and want requests for myfrog.org to be sent to your router -> server, you need to do something that is similar to port forwarding - but with DNS settings and your External IP address. This is typically done through an online interface maintained by the organization that provides the domain name.

Domain names can be obtained from a great variety of vendors. Simply search the web for "domain names" and you'll get a list. Registering your own domain name can cost real money. But there are free alternatives. An interesting one is to sign-up with a free "Dynamic DNS" service (DDNS). These free services will typically provide a unique "subdomain" on one of the many domains they control. Something like - thenameichose.heartsandflowers.com, where "thenameichose" is a subdomain of heartsandflowers.com. DDNS automatically updates your DNS record when your External IP changes. It does so using a program that you install on a machine within your local area network. The program periodically contacts the DDNS service provider with your account credentials (login name and password). The DDNS computer can check to see if the sender's External IP matches the IP address in your DNS settings.

My own preference has been to obtain (and pay for) a domain name along with an inexpensive hosting package. The hosting service provides space on their own servers and a way for me to control my own DNS settings. This document, for example, is on a hosting service computer. I log into my account and register subdomains myself, through their DNS settings pages with the External IP address of my own router. hll.nu is my domain. It points to the hosting service computer. Subdomain achieve.hll.nu, for example, forwards to the External IP address (and port) used by my own local Achieve server installation. I have been updating my DNS records each time my External IP address changes - about twice a year.

Create a subdomain that points to your Achieve server

At this point, all traffic that uses your domain name will be sent to a computer operated by your DNS provider / hosting service. You need to create a DNS record that will send traffic to the computer that is running your Achieve server.

Get your External IP address as explained above. (Section "Access from the World Wide Web")

In your DNS settings (log into the account you have with the service that provided your domain name), create an A record. If you have difficulty finding the right tab, consult the service's documentation or contact their customer support. For the name, enter "achieve" (without quotes). It is assumed that the form adds .yourdomain.com so that the result will be achieve.yourdomain.com. Enter your External IP address. Save / create record. Congratulations! You have just created a subdomain that points to your router. Try it by typing achieve.yourdomain.com into your browser's address bar.

Be aware however that once you have properly created the A record, it can take some time to "propagate" through to the many domain name servers that make up the DNS. My own experience is that this happens fairly quickly - in about 30 seconds or less. But it can take much longer. My hosting service warns that it can take up to 90 minutes.

Note also that normally, External IP addresses are not permanent. If you suffer a power outage or intentionally reboot your router, it is likely that you will receive a new IP address. When this happens, just retrieve your new address and update the A record.

HTTPS - HTTP-Secure, Introduction

HTTPS (HTTP Secure) addresses begin with "https://".

HTTPS encrypts communication - i.e. sends messages using "secret codes". This protects your communications from various high-jackers and such. Browsers are beginning to demand use of HTTPS whenever privacy may be a concern. Google has made it clear that it would like a future when everything on the Internet is secure. The Achieve server supports HTTPS, but you need certificates to use it.

HTTPS requires the use of security certificates. There are various types of certificates, with different levels of "authentication" - a step requiring proof that the applicant "owns" the domain that a certificate supports. Generally speaking however, there are two kinds of security certificates (as well as different file formats).

"Trusted Certificates" are obtained from a Certificate Authority (CA). To obtain a trusted certificate, you must have control of a domain name. The authentication step requires proof through a DNS setting. Certificates will be issued for the domain that you control. You cannot address your server on https://localhost with this type of certificate. You must use the domain name. Obtaining this type of certificate is what will be explained below.

The other type is known as a self-signed certificate. Self-signed certificates are often used during development and sometimes used within local area networks. With a self-signed certificate, you can address your server on https://localhost. You can create self-signed certificates yourself. If you are interested in self-signed certificates, search for the tool known as openssl. You might also be interested in Google's mkcert for creating what they call "locally trusted certificates".

I have never set up https using a free DDNS, but here's a 2018 article by someone who says that he has.

The following two sections explain how to obtain security certificates for HTTPS and DNS settings for HTTPS.

Cost-free, trusted security certificates

To obtain trusted certificates, you need to have control of a domain name.

Once you have a domain name, find out how to log in to your account; i.e. with the hosting service or other vendor that provided the domain name. Find the page used for DNS settings - and then possibly a tab for DNS records. During the process of obtaining certificates, you will need a TXT record. If you have difficulty discovering how that's done, contact your vendor's customer support.

The easiest way that I have found to obtain certificates is through SSL For Free. SLL For Free provides a very simple way to obtain cost-free trusted certificates from Let's Encrypt, a well-respected Certificate Authority that was set-up to provide Trusted Certificates free of charge. The certificates you receive will be valid for 90 days. If you provide your email address at the end of the process, SSL For Free will send a reminder when you need to renew them.

At SSL For Free, type *.yourdomain.com where it says to "enter your website to secure". Use your domain name in place of yourdomain.com. Do not include www. Don't forget the *. This will give you certificates for your domain and all its subdomains, for example; www.yourdomain.com, achieve.yourdomain.com, myapp.yourdomain.com and so on. You will decide which subdomains are forwarded to your Achieve server using DNS settings - at the same place you will soon be creating a TXT record.

Click the "Create Free SSL Certificate" button and follow the instructions. The instructions will tell you how to set up the TXT record. When setting up the TXT record, make sure that you get the right result. (NOT with name ending with duplicate yourdomain.com.yourdomain.com.)

You can attempt the next step once you have created the TXT record. The CA will attempt to read the TXT record via your domain name. When successful, this confirms that you have control of that domain. The SSL For Free instructions explain that if you get an error when trying this step, just wait a bit and try again. The TXT record might not have propagated yet. If you need to wait, just be sure that the TXT record was created properly - i.e. without double entry of your domain name and that the name and value are the ones that were provided to you.

When the confirmation step is complete, you will be issued a set of certificate files. Use the button at the bottom of the page to download all three files together. Put that file in a convinient location - for example c:/certs/ directory. Unzip the files to that location.

You can now set up and test HTTPS on your Achieve server. Follow the Achieve server instructions to start HTTPS. Based on the example given above, you have created an A record for achieve.yourdomain.com

If you are using port 443 (the HTTPS default port), test: https://achieve.yourdomain.com

If you are using port 7777, test: https://achieve.yourdomain.com:7777

DNS settings for HTTPS

To send HTTPS traffic to your Achieve server using a custom subdomain, the DNS settings need to be slightly different than those you learned about above. (Section "Create a subdomain that points to your Achieve server") You need to set up records that include the "https://" protocol specification. I use both forwarding and aliasing. Forwarding changes the address that you type into the address bar. Aliasing does not.

Based on instructions above, you should already have an A record that points to your router. This document called it achieve.yourdomain.com. Create a new forwarding or aliasing record using subdomain sachieve.

If you are using port 443 (the HTTPS default port), the value can be: https://achieve.yourdomain.com

If you are using port 7777, the value must be: https://achieve.yourdomain.com:7777

Once the new DNS setting has propagated, secure traffic will come to your server using address sachieve.yourdomain.com