Skip to main content

Quick Start

The Quick Start guide outlines the process of setting up a private IP connected to a setip.io (PoC) account using WireGuard. It explains two modes: Transparent mode for all traffic and Proxy mode for HTTPS. The steps involve installing WireGuard, configuring devices via setip.io admin control panel, and connecting origins through automatic or named URLs. Automatic URLs use the private IP’s last digit in the URL, while named URLs offer custom names. It also details deploying static web apps and code through buckets associated with specific URLs, providing steps for manual and CI/CD deployment.

By bringing up a private IP that is connected to the same private network as your setip.io PoC account you automatically route traffic to and from a device of your choice. You can route all traffic (setip.io Transparent mode) or only HTTPS (Proxy mode), depending if you wish to let SETIP.IO handle TLS certificates for your URL or if you want to do it yourself.

For running your code or any 3rd party code on your laptop and expose its listening port(s) with a setip.io supplied URL, you will first need to ensure WireGuard is already installed, it usually is if running a recent version of Linux and may not be if running Windows or a Mac computer. You can read further and install it if not already present. Once WireGuard is installed, it is configured with a simple configuration file on Linux and can be imported from the same file on Windows and Mac hosts.

Configuring any device to enable its private IP is greatly simplified when using the setip.io admin control panel, where you can copy and paste the proper configuration file for each available device on your local network. This will also enable the WireGuard configuration on the device and will assign it your private network IP address beside its existing IP address if it is not already installed and the host is Linux.

Once a device is connected with WireGuard its HTTP port will be reachable through one of two types of TLS protected URLs: automatic URLs and named URLs.

Automatic URLs contain the device and port you want to reach in their name, so they are not to be used for brands association as much as named URLs. Usually you will need the automatic URLs for dev so you can go faster and used named URLs later for deployment and production deployments.

Step 1: Connect your laptop or servers to your PoC private IP​

This is also the only step if using Automatic URLs, you can read below on how to use Automatic URLs after you go through this step.

To install WireGuard on any host if not already installed you can follow this link or, if running Linux Ubuntu, you can install, configure and connect a peer in less than a minute by clicking on the button under the Wireguard install + Config to clipboard (Linux). column of the Peer table. The Peer table is located under the Network tab of the Admin panel. Below is a screenshot of where to grab the installation script to install Wireguard on your device:

Device configuration

If WireGuard is already installed, simply paste the content of the clipboard after you click on the button named: "WireGuard install + Config to clipboard (Linux)". You can also click or download the configuration file on the button under the "WireGuard config to file" column to download the config to a file, sometimes only a configuration file can be used, so it comes handy.

If WireGuard is not installed, the easiest is to install it along with the configuration for the peer by clicking on the icon under the "WireGuard install + Config to clipboard (Linux)" column for the peer number you want to assign to that device.

For each peer configuration, you will find the following copy/paste button you can click on to copy to your clipboard what will be used to configure the device you assign a peer to.

  • WireGuard Config (All OS) to clipboard. To be used to paste a WireGuard configuration requested in a router or in the Mac or iOS app when no file can be imported. This will allow you to paste the configuration when available.

  • WireGuard install + Config, to clipboard (Linux). To be pasted on a Linux host where no WireGuard is currently installed yet, it will run a full WireGuard install plus configure the host and connect to the setip.io POC, assigning the private IP of the peer as a private address to the host, each peer's configuration matches the line number where the copy button can be clicked.

  • WireGuard config to file. To save a WireGuard configuration to be imported into WireGuard for the peer host.

Named URLs

Step 2: Connect your laptop or servers to public or restricted public URLs​

Before you can connect your apps, or third-party apps, and access them through secured URLs you will need to connect that device to your setip.io account. You can copy and paste the install script for each device from the Network tab in the Admin Control Panel as you will read below under the Named URL paragraphs.

Automatic URLs​

Automatic URLs are easy to use, memorable, and secure URLs, such as https://3-3000.yourorg.wg0.io.

The first digit (3) before the "-" character in the URL matches the last digit of the private IP address for the device you want to reach, so in that example, the private IP address could be 172.23.44.3 and since it ends by .3 you will use 3- to reach any port on that machine. Then you use the port number you want to reach after the - such as -3000 to reach port 3000 in the previous URL used as an example.

This URL makes it easy to remember how to reach a port on any machine: your laptop or a container running inside a Kubernetes cluster, for example. By simply changing the first digit you can securely reach any of your devices from the Internet or your private network, through the device's setip.io assigned private network IP address. By changing the port number after the - you can reach any port number on any device.

If your development setup requires multiple ports, you can even use one stable URL per port, as long as you keep using the same internal IP for all listening ports.

Named URLs​

Named URLs are simply URLs that you can create with a name of your choice such as: urlwiththenameofyourchoice.yourorg.wg0.io and point them to any port listening on a device/peer where you can run WireGuard (You can add your device/peer by picking its configuration from the Network tab).

Named URLs

To create a new URL simply click or tap on the + icon from the URL tab in your setip.io Admin Panel.

Named URLs

You will be asked for the hostname (Fully qualified, meaning you should type hostname.yourorg.wg0.io as opposed to just hostname).In the screenshot example below you can see that we create a URL: https://teama.yourorg.wg0.io. It will be pointing the public to a web app listening on port 3000 on a server we keep in-house.

In our example, the server could be a container running under docker on your dev machine to try out securely, is an Ubuntu OS image and will be running the configuration file for WireGuard assigned to peer7, hence the origin: http://peer7:3000 (see above to assign a configuration file to the host which port you want to expose).

Then, just indicate the path as a simple "/" or add any path if you want to specifically direct all access to that URL and specific path to a different host (For example, if URL visitors add: /api after the URL such as in https://yourorg.wg0.io/api they would be directed to a server running at a cloud vendor while the main site https://yourorg.wg0.io can run on your setip.io PoC at no extra cost, as a static site and updated automatically from code or CI/CD at a later stage).

Finally indicate the Origin for the URL and the path, meaning where traffic will be sent when people's browsers or apps will be hitting that URL and path. That can be your laptop or another device (For example a docker container running off the cloud or a local machine). Typically it can be your laptop until you deploy, then you will want to create a special host for your laptop and use it for development purposes so you can keep the / for staging or production versions of your listening, versions that change less frequently as the dev version.

Named URLs

The result should look like the one below after you save it.

Named URLs

Step 3: Deploy an "always-on" static web app​

You can upload your static site files into "Buckets" that you can simply associate with a URL of your choice just by naming the bucket as an origin.

Buckets are very handy: you can fill them by uploading a simple zip file of any directory content, such as the "build" or "dist" directory that, with most tool chains, will contain your deployment files after build.

The zip file will be automatically decompressed in the bucket after being uploaded. So all you have to do to deploy a site: you zip the files used to serve the site and upload it manually or through a script to one of the buckets, then you can insert this script in your CI/CD process if already setup or later so it triggers automatically from your git repositary.

Buckets can be used to deploy a "Staging" and "Production" versions of your site currently under development.

There are five buckets available for static web sites served over https so, for example: One bucket can be used for your main web site, another bucket can be used for online documentation and a third bucket can be used for a blog, each bucket is associated with a specific named URL pointing to each bucket.

Each bucket has a default URL so its content can be accessed even if no URL has been setup manually to point to it. This is bN (b1, b2, b3, b4, b5) before the PoC domain name (YourPrefix.wg0.io or your own domain name).

  • Default URL for Bucket 1 is https://b1.YourPrefix.wg0.io
  • Default URL for Bucket 2 is https://b2.YourPrefix.wg0.io
  • Default URL for Bucket 3 is https://b3.YourPrefix.wg0.io
  • Default URL for Bucket 4 is https://b4.YourPrefix.wg0.io
  • Default URL for Bucket 5 is https://b5.YourPrefix.wg0.io

To link a bucket to a named URL simply insert the bucket's name to its origin. Use "b1" as an origin instead of the usual http://x.x.x.x:yyyy destination for the origin.

From the terminal​

You can now copy the script described in the steps below with values already matching your configuration so as to bootstrap your own script. If you choose the buckets named "b1" to "b5" as origins for the URLs you define you will see an icon appearing to the right at the bucket name. Simply click that Copy icon to paste the pre-configured script content directly in your text editor. Copy preconfigured bash script to upload static site to bucket

  1. Copy the following lines in the terminal (Do not include the square brackets as they show explain values to be replaced with the values for your account):
  • [static_deploy_login_token] is available under the Keys tab in the setip.io web site management console.
  • [bucket_number_from_1_to_5] lets you choose from b1 to b5 prefix before your domain name:
#!/usr/bin/env sh
cd build
# Zip files in the build directory, IMPORTANT: using -D option to restore files in the archive without a containing folder name.
zip -r -D [fullpath_to_your_web_directory]/zipped.zip *
# Curl command to upload the zip file to the bucket, IMPORTANT: replace with your info.
curl --location 'https://b[bucket_number_from_1_to_5].[your_setip_io_domain]/upload' \
--header 'Authorization: Bearer [static_deploy_login_token]' \
--form 'files=@"[fullpath_to_your_web_directory]/zipped.zip"'
  1. From the terminal, go to the directory containing your project build. This directory is usually named "build" or "dist" and is generated by your framework build command. Paste the command above (change the values accordingly).

From CI/CD​

You can copy the script above to be executed by any CI/CD environment but make sure you use the provided system env variable to store the value to replace [static_deploy_login_token] as indicated in the script above.

Step 4: Deploy "always-on" code​

You can upload your code files into your always-on "Buckets" numbered six to ten. There are only five buckets available for performance reason so when we activate our DCCDN (Distributed Code Cache Delivery Network) initially we can keep an acceptable performance level while distributed to our peers.

Your code is immediately executed after being uploaded and runs for 60 minutes or more before being restarted so it must be stateless (You can persist data through the network but not to local storage).

For now, the only way to stop your code from running is to code it to stop itself or simply upload a zip file to the matching "bucket" containing your running code with a single file named stop into it.

The execution environment for the code you upload is Wasmedge. WasmEdge is a CNCF (Cloud Native Computing Foundation) sandbox project. You can install wasmedge on your local machine for coding and debugging before you deploy your code "always-on" to your bucket, so it can execute even if your dev machine is shutdown. Documentation for Wasmedge is available here: link.

Both type of bootstrap files index.js and index.wasm will be executed immediately through the WASM interpreter. If using an index.js bootstrap file this is used to allows node.js compatible code to run in "wasm" mode: wasmedge-quickjs (if running an index.js file, you must, at least, include the wasmedge_quickjs.wasm in your build directory so it will be available to wasmedge otherwise js execution will not be available).

The example below, which repository is available here and which content is reproduced below, shows how your app can listen to any of your URLs quickly: Simply point any of your URLs to an origin named "b6" to "b10" and it will directly expose your app listening port to that URL. As you can see env.SETIP_LISTEN_PORT contains the port matching the short name "b5" to "b10".

import { createServer, request, fetch } from 'http';
const PORT=env.SETIP_LISTEN_PORT;
createServer((req, resp) => {
  print("server: req.httpVersion=", req.httpVersion);
  print("server: req.url=", req.url);
  print("server: req.method=", req.method);
  print("server: req.headers=", Object.keys(req.headers));

  req.on('data', (body) => {
    print("server: req.body=", body);
    print()

    resp.write('echo me:')
    resp.end(body)
  })
}).listen(PORT, () => {
  print(`listening  on ${PORT} ...\n`);
})

Buckets can be used to deploy a "Staging" and "Production" versions of your code.

Each bucket has a default URL so its content can be accessed even if no URL has been setup manually to point to it. This is bN (b6, b7, b8, b9, b10) before the PoC domain name (YourPrefix.wg0.io or your own domain name).

  • Default URL for uploading to Bucket 6 is https://b6.YourPrefix.wg0.io
  • Default URL for uploading to Bucket 7 is https://b7.YourPrefix.wg0.io
  • Default URL for uploading to Bucket 8 is https://b8.YourPrefix.wg0.io
  • Default URL for uploading to Bucket 9 is https://b9.YourPrefix.wg0.io
  • Default URL for uploading to Bucket 10 is https://b10.YourPrefix.wg0.io

Buckets are very handy because you can fill them by uploading a simple zip file of your build directory content. The zip file will be automatically decompressed in the bucket after being uploaded. So all you have to do to deploy a site is to zip the files used to serve the site and upload manually or through a script to one of the buckets.

To deploy your code:

From the terminal​

  1. Copy the following lines in the terminal (Do not include the square brackets as they show explain values to be replaced with the values for your account):
  • [static_deploy_login_token] is available under the Keys tab in the setip.io web site management console.
  • [bucket_number_from_1_to_5] lets you choose from b1 to b5 prefix before your domain name:
#!/usr/bin/env sh
cd build
# Zip files in the build directory, IMPORTANT: using -D option to restore files in the archive without a containing folder name.
zip -r -D [fullpath_to_your_web_directory]/zipped.zip *
# Curl command to upload the zip file to the bucket, IMPORTANT: replace with your info.
curl --location 'https://b[bucket_number_from_6_to_10].[your_setip_io_domain]/upload' \
--header 'Authorization: Bearer [static_deploy_login_token]' \
--form 'files=@"[fullpath_to_your_web_directory]/zipped.zip"'

cd to the directory containing your project build. This directory is usually named "build" or "dist" and is generated by a build process. Paste the command above (change the values accordingly).

From CI/CD​

You can copy the script above to be executed by any CI/CD environment but make sure you use the provided system env variable to store the value to replace [static_deploy_login_token] as indicated in the script above.