Setup & Install
Acronyms
- VPS | Virtual Private Server | A server hosted in a datacenter.
- ISP | Internet Service Provider | The company you pay for internet access.
- IP | Internet Protocol | How computers communicate over the internet.
- IPv6 | IP version 6 | Very slowly replacing IPv4.
- NAT | Network Address Translation | Used in all IPv4 home routers.
- OS | Operating System | E.g. Linux, Android, Windows.
- CA | Certificate Authority | A trusted entity that signs certificates.
- URL | Uniform Resource Locator | Goes in the browser's address bar, e.g. https://example.com/
Choose where to host
WireTile is self-hosted, which means you decide where to host it. There are generally 2 options:
At home
Host at home using your own home server and residential internet connection.
A home server is simply a computer you own that stays powered on and is connected to your home network. Almost any computer will do,
such as an old desktop or laptop.
- You own the computer, as opposed to renting one from a datacenter.
- Reuse old computer hardware.
- Experience can vary depending on home network, mainly if router supports UPnP or not.
In a datacenter
Host using a VPS from your preferred cloud hosting provider.
A low cost VPS will suffice, such as
Vultr's $5/month.
- Solution for home ISP not providing a public IP address (carrier-grade NAT, double NAT).
- Static IPv4 and IPv6 address. Most residential ISPs don't offer static IPs.
- Requires registering/managing an account with a cloud hosting provider.
- Monthly costs can quickly exceed upfront cost of home server hardware.
Server setup
For simplicity these instructions will assume the server is running Linux
Ubuntu Server LTS x64. For most other distros these steps would be
similar if not identical.
Install WireTile
- Create a directory
mkdir ~/wt && cd ~/wt
- Download
curl -O https://wiretile.net/dl/wiretile-latest-linux-x64.tar.gz
- Extract
tar -xf wiretile-latest-linux-x64.tar.gz
- Create a Systemd service as shown below. Docker is also shown if you prefer using containers instead.
Systemd
- Create a Systemd service for WireTile
echo "
[Unit]
Description=WireTile
After=network.target
[Service]
ExecStart=${HOME}/wt/wiretile
Restart=on-failure
User=$(id -u)
[Install]
WantedBy=multi-user.target
" | sudo tee /usr/lib/systemd/system/wiretile.service
- Start on bootup
sudo systemctl enable wiretile
- Start
sudo systemctl start wiretile
Additional useful commands:
- Stop
sudo systemctl stop wiretile
- View status
systemctl status wiretile
- View logs
journalctl -eu wiretile
Docker
- Navigate to directory
cd ~/wt
- Create a compose file for WireTile
echo "
services:
app:
image: ubuntu:latest
restart: unless-stopped
user: '$(id -u)'
network_mode: host
working_dir: /srv
command: /srv/wiretile
volumes:
- ./:/srv
" | tee ~/wt/docker-compose.yml
- Create and start container
sudo docker compose up -d
Additional useful commands (assumes in directory ~/wt):
- Start
sudo docker compose start
- Stop
sudo docker compose stop
- View status
sudo docker compose ps
- View logs
sudo docker compose logs
Additional useful commands:
- View network interfaces and IP addresses
ip address
- View processes and ports listening on network
sudo ss -nltup
Certificates setup
The Web App expects your devices (e.g. desktop/laptop, phone) and server to trust web connections to/from each other. This is
accomplished by using the certificate-authority.pem and client-certificate.p12 certificate files, which
would be located on your server at ~/wt given the above instructions.
This process only has to be done one time per browser/device, unless in the future you decide to regenerate the certificates via the
wiretile delete-certificates command.
What are these .pem and .p12 files?
These files are generated locally/offline when you first run WireTile and are unique to you.
-
certificate-authority.pem is a CA certificate file. The browser will use it to verify that you are in fact
connecting to your server and that the connection is secure. It gives the "secure padlock" icon/text in the browser's url bar.
-
client-certificate.p12 is a client certificate file. The browser will present it when connecting to the server, and
the server uses it to decide if it will allow the connection or not. Devices without it will be rejected by the server. It is
analogous to a ID card or password, but more secure.
Lookup asymmetric or public-key cryptography if interested in more details.
How do i send/copy the certificate files to my devices?
From server to desktop/laptop
Use the scp command to copy the certificate files from your server to your desktop/laptop.
For example, you would run something like
scp [email protected]:~/wt/certificate-authority.pem ~/Downloads/ from your
desktop/laptop, of course replacing this example's placeholder values with those appropriate for your setup.
From desktop/laptop to mobile device
There are many ways to send files between desktops/laptops and mobile devices. Use any method that is convenient for you, so
long as the certificate files remain private and only visible to you, i.e. don't share them publicly.
For example:
- Use a network-based file sharing app such as Quick Share or KDE Connect.
- Use a local/cloud network storage app.
- Connect devices together via a USB cable.
- Use an external storage device such as an SSD or SD card to ferry files.
First copy the certificate-authority.pem and client-certificate.p12 certificate files to your device's
Downloads folder, then add/import them as shown below. Afterwards you can delete them from the Downloads folder.
If prompted for a password when adding client-certificate.p12 simply leave it blank and continue.
Desktop
Add certificates to the web browser:
-
Firefox:
-
Navigate to
about:preferences#connectionSecurity
> Manage certificates.
-
"Authorities" tab > Import > select
certificate-authority.pem from Downloads folder > tick the checkboxes.
- "Your Certificates" tab > Import > select
client-certificate.p12 from Downloads folder.
-
Chromium-based:
Mobile
Add certificates to the OS:
- Settings > search for "ca certificate" and select the first search result.
- CA certificate > Install > select
certificate-authority.pem from Downloads folder.
- App user certificate > select
client-certificate.p12 from Downloads folder.
Web App
WireTile's logs will display a "Web App URLs" section listing the URLs to access the Web App. See
Server setup for command to view logs. From your device (e.g. desktop/laptop, phone) navigate to the URL
using a web browser. There can be up to 4 URLs listed depending on your network setup, in which case try each until one succeeds.
On mobile using a Chromium-based browser is required, because mobile Firefox doesn't support client certificates.
Reminder that
Certificates setup must be completed on the device in order for it to access the Web App.