A tutorial that demonstrates how to install your own domain into Vortex so that you may intercept traffic based on rules you create for faster observability, replay, and debugging.
A video walkthrough of this tutorial is available on YouTube.
Register or sign into Vortex
The first thing you will need is a Vortex Account which you can get by registering today.
The next thing you will need is a public domain name that you own. More to the point, you will need access to the DNS where this domain is pointed and permission to make changes.
And finally, if you plan to secure your website with HTTPS, you will need access to the website where you purchased your certificate.
One last comment... It's assumed that you have followed the quick start tutorial on instant domains before starting this tutorial. The instant domain tutorial gets you started in Vortex and explains some of the basics. In this tutorial, we will add upon what you learned in that prior video.
Start with the Sites screen
Click Sites on the left menu after you sign in. On this screen you can see all the domain names you have added to Vortex. By default your account comes with one instant-domain. Follow these instructions to add your own domain.
Choose Add New Site
This form lets you add an instant domain or owned domain. Start by clicking the Owned Domain option at the top of the form.
It is important to realize, instant domains let you expose your local computer to the internet using a public domain name that Vortex provides you. Owned domains are an entirely different ball game. With this feature you are using Vortex like a firewall or content filter. As data flows, Vortex lets you define traffic rules that change the behavior of the data instantly. Below are some examples of the Vortex rule types and how they affect your websites traffic.
Debug - Traffic will be suspended in-flight and delivered to a developer running the Vortex Shell. This developer becomes a temporary member of your web application. If they are running the source code in a debugger then it will be triggered exactly like the call was made to their local machine. In this way the developer may hit a real breakpoint in their IDE and step through the code line by line. Any response the developer provides is injected back into the pause transaction before it is resumed. If no response is provided, the call will eventually time out.
Monitor - Traffic will flow like normal but the request and response data will be journaled. From the journal you can inspect the data and search for bugs or even replay the data so it can be delivered to a developer running the source code.
Trash - Traffic that matches this rule will go directly into the garbage.
Enter site information
Enter the domain name you wish to add. This is the fully qualified domain name such as www.mysite.com or api.myapp.com. If you only enter the top-level domain name myapp.com then Vortex will only handle traffic if that specific address is used. Normally, this is not the case. A typical website lives in a sub-domain like www or api and the top level domain name only redirects traffic there.
Enter the IP address of your domain name. If this domain name is already setup outside of Vortex and working, you may find the IP address at your DNS provider or using 'ping' but be careful. You don't want the internal IP address like 192.168.1.2 or 10.1.2.3. You want the public IP address accessible over the internet by anybody. If this is a new app, enter the public IP address your hosting provider assigned you. For example, if you are hosting in Azure using an App Service you will see your public address called (Virtual IP) located in the Properties tab on the left menu after logging into portal.azure.com.
Choose which service and ports to bind. These field are already chosen for you using values for standard web behavior but you may override them if your needs are different.
Save your changes
That's it, click Add Custom Domain to install your new site into Vortex.
Service Provider Info
In this tutorial, the DNS and SSL setup at your service provider's site is not covered in detail. Check back soon for a tutorial that covers each topic completely. Until then, contact support or join us on Discord and we will gladly walk you through the process in person.
Setting up your own domain in Vortex requires a few manual changes. One is at your DNS provider and one is at your SSL Certificate provider.
With these steps, you will instruct your DNS provider to send traffic to Vortex and then based on ad-hoc rules you create, the traffic will either be routed to your hosing provider, paused while a developer takes a look, or logged for further analysis. Traffic that does not match any Vortex rule will flow like normal to your hosting provider.
By uploading a valid SSL certificate, your encrypted traffic can be decrypted before it lands in the journal.
Update your DNS settings
On the sites screen you should now see a yellow warning sign next to the DNS status of your site. In this message there is an IP address listed. You must edit the A record at your DNS provider and point your host name to this IP address.
Upload your SSL Certificate
You will need a copy of your SSL Certificate in PEM format if you chose to enable HTTPS traffic. This certificate is composed of 2 or 3 keys and may be downloaded from provider where you purchased it. Make sure you get the public key, private key, and optionally the intermediate key. Tools like OpenSSL are very helpful in this step in case you need to convert a certificate into PEM format.
Once you have all the pieces assembled into a single PEM file, click the Certificates option on the left menu. There is a handy button titled Upload Certificate located in the top left section of this screen.
If you have access to the various keys, you can also copy and paste them into a single file having a file extension of PEM. The file will look something like this when you are done.
Check your status
On the sites screen in Vortex you can see the status of your Owned Domain. DNS changes may take up to 2 hours to take affect across the internet. There is nothing Vortex can do to speed this up. Check this screen often for all the check boxes to turn green.
Give it a try!
Now that your site has been added and your manual changes are out of the way you can give it a test. Load your domain name in your favorite web browser and make sure it still works just like before.
Turning off Vortex
If you wish to turn off Vortex, change your public DNS back to the original Target IP address. You can turn it back on at any time and there is no need to change anything in Vortex.
Check back here for more tutorials that cover things like Adding Rules, Inspecting the Journal, Replaying Transctions, and Realtime Debugging.