Introduction

This is the documentation for the first workshop play-test hosted at Creative Coding Utrecht. This workshop is initiated by marie verdeil (verdeil.net) and Rein van de Woerd (rein.computer).

Inspiration & Similar projects:

Resources

Skills

To comfortably follow this tutorial, some basic knowledge of the command line interface (terminal) is advised. Basic knowledge of HTML, CSS is preferable. 

1. Setting Up: SmartPhone

A. Phone requirements

Android smartphones and tablets that are less than roughly 10 years old should all be suitable for this tutorial. In case your phone is older or not an Android phone, look below at the alternatives. 

Your phone could be a bit damaged but the following features are necessary:

  • Android 5 or above (Android 7 or above is preferable) (check in settings)
  • The Wi-Fi card functions and you are connected to a Wi-Fi network

Optional but better: 

  • The touch screen works, even though it could be shattered. If you don’t have a working screen, check out these solutions.
  • The charging port works. 
  • The battery functions, or you have an external battery.

Alternatives - iPhones and iPads

Termux is not available on iOS but there is an alternative called iSH available on iOS 11 and +. Some webserver tutorials are available online (using iSH and python webserver).  

Alternatives - PostMarketOS

If your Android phone is simply too old, cannot update or you are looking for a different approach, check out PostMarketOS. 

PostMarketOS is an alternative Linux OS that is free, open-source and community maintained. You can install it instead of Android and extends your phone’s lifespan beyond its programmed software obsolecense (lack of updates). You can then easily install the webserver of your choice. 

B. Optional: Factory Reset your Phone + Google’s FRP

This step is optional, but it might be handy to clean up your phone before deploying it as a webserver. It will give you more storage space, and prevent other apps to overtake computing power.

To do this, online search your device model + factory reset. You will find some instructions to access the boot mode of your computer, from which you can select wipe phone or factory reset. A good website is Hard Reset.

Before you reset your phone: - Back-up the the contents your want to save - Make sure to disconnect any Google Account in Settings > Accounts. Otherwise you risk facing Google’s FRP protection prompting you to login again to the previous Google account. This makes it harder to start with a phone you bought or got from someone else.

2.Install Dependencies

List of software we will be using: 

  • On the phone:
    • Termux
    • Termux API
    • OpenSSH
    • Nginx
    • PHP (optional)
  • On your laptop (optional but handy):
    • Laptop’s terminal or PUTTY on Windows.
    • A Code Editor to edit HTML (VS codium, Sublime Text, etc.)
    • FileZilla or another SFTP client to transfer files to your server

Make sure you download the necessary solftware on the laptop. Now, your smartphone is ready: we move on to downloading the necessary apps. 

A. Install Termux

Termux is a terminal emulator and package collection. You can access its wiki here. 

Download it from the F-droid webpage or from the F-Droid App if you already have it. 

/!\ Do not install using the Google Play Store

  1. Go to https://f-droid.org/en/packages/com.termux/
  2. Download the stable (suggested) version (not beta) by selecting Download APK. 
  3. If your phone runs Android 5 or 6, Downlad the universal package from here (select termux-app_v0.119.0-beta.3+apt-android-5-github-debug_universal.apk)
  4. Once downloaded, tap the APK on your device
  5. Tap allow installation of apps from unknown sources (you will want to set this option anyway to be able to install apps built on your device in Termux),
  6. Allow the installation to complete,
  7. Once installed, you will see the Termux launcher on your home screen and in your App Drawer. Tap the icon to fire up the application.

B. Install Termux API

This sister app gives you access to some of your phone hardware features. documentation here. We have to install it twice: first the app, via F-DROID (step 1.) gives us access to the phones inner features. Then inside Termux (step 3.) to be able to call the API via the Terminal.

/!\ Do not install using the Google Play Store

  1. Go to F-Droid and download Termux API and select Downlad APK. 
  2. Tap Termux API app on you home screen, you will be redirected to the settings: 
    • Check all the red buttons: disable battery optimisations
    • Allow display over other app
  3. Open Termux and write each line, then hit enter.
pkg update && pkg upgrade -y
pkg install termux-api
  1. Set-up Termux storage (more info here)
termux-setup-storage

Tap to grant permission

  1. Check if it all works by entering: you phone should vibrate
termux-vibrate

C.SSH Access : OpenSSH

This step is optional or can be done later.

Install OpenSSH on your phone to be able to remotely access (using SSH protocol) the device via your laptop’s command line interface or SFTP client.

  1. Find Termux Username: type + enter
$ whoami

Write down the result for later, it should be similar to:  u0_a96

  1. Set a password with passwd:
  • Install termux-auth and then you can use passwd:
$ pkg install termux-auth -y
$ passwd
  • Type your password + enter / Type again to confirm
  • Write it down somewhere to remember it
  1. Install OpenSSH:
$ pkg install openssh -y
  1. Start SSH server: - Identify the local IP address of your phone by typing + enter
$ ifconfig
  • Write down the IP address to remember it. It’s the one written after wlan0: … inet… and probably looks like: 192.168.XX.XX
  1. Start the ssh server:
$ sshd
  1. [From your laptop] Connect to phone via ssh: Make sure you are connected to the same Wi-Fi network
  • On your laptop, open the terminal app (MacOS, Linux) or PUTTY (Windows). 
$ ssh -p 8022 [username]@[ip address]
  • In the command above, replace [username] by the username (step 1.) and [ip address] by your local ip (step 4.2.) and press enter:
$ ssh -p 8022 u0_123@192.XX.XX.XXX

- You will get the following message: Are you sure you want to continue connecting (yes/no/[fingerprint]) - Type yes and hit enter. - DONE! YOu can now enter command in your laptop’s terminal to control your phone.   7. Check if your phone vibrates by remote command:

$ termux-vibrate
Know-How:
  • Stop the SSH server: pkill sshd
  • Disconnect the SSH session from your laptop: exit

D. Install a webserver: NGINX

From Termux interface on your phone or from your laptop via SSH, you can install nginx, a very basic and popular webserver.

  1. Install nginx:
$ pkg install nginx -y
  1. Start-up and test the server:
$ nginx
Know-how:
  • Status nginx server: systemctl status nginx
  • Stop server systemctl stop nginx
  • Start server systemctl start nginx
  • Refresh server: systemctl reload nginx
  1. Open a browser on your phone and type: http://localhost:8080 or http://127.0.0.1:8080
  2. You should see nginx starter page: “Welcome to Nginx”
  3. Get your ip address and write it down:
$ ifconfig
  • It should be written under _wlan0: ... inet... 192.168.XX.XX_
  1. Visit your the website from another device:

Make sure you are connected to the same Wi-Fi network

  • Open a browser on your laptop and type the following: http:// + [the ip address] + :8080
  • Make sure you use http:// and not https:// (we don’t have a secure SSL certificate yet).
  • It should look something like this: http://192.168.1.1:8080
  • You should see see nginx starter page: “Welcome to Nginx”.

3. Setting-up Webserver

A. Edit HTML files:

Option A: In the command line (on your phone or via SSH)

On termux, the served files can be found at the following address: $PREFIX/share/nginx/html

  1. Navigate to the html folder (type +enter)
$ cd $PREFIX/share/nginx/html 
the full path will be --> $ cd /data/data/com.termux/files/usr/share/nginx/html/
$ ls
  1. You should see 2 files: index.html and 50x.html. index.html is the main page while 50x.html displays on specific error. You can edit the main html page
$ nano index.html
  1. Change some text in the header and save by using ctrl + X
  2. (Hard) Refresh your browser page and you should see the updated page.

Option B: Via SFTP in FileZilla

Whether you want to upload an exisiting static website (a folder with HTML files, images, CSS files, etc.) or you want to do make a new page, it’s easier to do so on your laptop and transfer the files over SSH via the Ssh File Transfer Protocol (SFTP). 

Make sure you have installed OpenSSH in Termux (see SSH section)

  1. Download FileZilla or another SFTP/FTP client on your laptop. 
  2. Fill in the following fields in the site manager and hit enter: - Protocol: SFTP - Host: your local IP address of your phone 192.168.XX.XX - User: your ssh username (see SSH section) - Password: your ssh password (see SSH section) - Port: 8022
  3. Once connected, navigate on the remote side to the html folder - Enter the path in the search bar: /data/data/com.termux/files/usr/share/nginx/html - Or navigate using the file manager tree interface. 
  4. You can now drag and drop files and folders into the html folder. Do not delete the html folder. 

E. Go Online via Proxy:

There are several ways to open a local server to the public over internet. Essentially it consists in explaining to a DNS at which public ip address your website can be found so visitors can be directed there. There are several ways to do this.

  • If your home/work internet router has a fixed IP address, it is definitely the easiest, and there are many online tutorials for this. 
  • Another approach is a dynamic DNS, wbut we won’t be using this here. 
  • The last approach is using a reverse proxy tool like BoringProxy or Ngrok. A comprehensive list is available here. 

Using SirTunnel:

SirTunnel is a self-hosted reverse proxy. It works with ssh and functions in Termux. You need to install it on a server with a fixed IP address (your own server) and purchase a domain name. We got comphost.club, so everyone in the workshop can have a subdomain in that list:

  • In termux , type the commad below, replacing:
  • [your-subdomain]: by the subdomain you would like to have. It has to be unique: example.comphost.club
  • the port 9001 by another unique port, like 9876. 
ssh -tR 9001:localhost:8080 comphost@comphost.club ./sirtunnel.py [your-subdomain].comphost.club 9001
  • Hit enter then type the password (or ask us for it).
  • Success, you should be online at: https://example.comphost.club**

Using a proxy service like ngrok or localhost.run.

With localhost.run: in the CLI type and enter:
$ ssh -R 80:localhost:8080 localhost.run

Type yes + enter to connect. You will get a temporary domain name to looks something like https://46dd096d0d85c2.lhr.life. If you want to add a custom domain you will have to pay. 

With ngrok:
  1. Install ngrok in Termux: 
$ pkg update -y
$ pkg install git
$ git clone https://github.com/Yisus7u7/termux-ngrok
$ cd termux-ngrok
$ bash install.sh
  1. Sign-up to ngrok:
  • Visit ngrok.com
  • Sign-up and verifiy your email address.
  1. Copy your auth-token in the relevant section and add it to the config: 
  • Enter the following command, replacing [auth-token] by the auth-token you just copy-pasted.
$ ngrok config add-authtoken [auth-token]
  1. under static domain copy and past the command, changing port 80 to port 8080
$ ngrok http --url=gorilla-champion-tomcat.ngrok-free.app 8080

Check ngrok configuration and paid tiers to get more advanced configuration. For example, to set a custom domain

F. Exploring potentialities

Control Phone’s Features via PHP

Soon

Remote Phone Vibration

Soon

G. Update website regularly via CRON

$ pkg update
$ pkg install cronie termux-services
  • launch cron and add/edit cron jobs: 
$ crond
$ contab -e
  • copy and paste the following commands before saving
# Gets battery status in JSON and paste it into the HTML every five minutes
*/5 * * * * termux-battery-status >  /data/data/com.termux/files/usr/share/nginx/html/battery.json

https://hugmouse.github.io/gotermux-docs/0.1/termux-api/termux-battery-status/


# Gets battery plugging status every minute and place that value in a json file 
*/1 * * * * termux-battery-status | grep "plugged" -m 1 >> /data/data/com.termux/files/usr/share/nginx/html/plugged.json


# vibrates every minute
*/1 * * * * termux-vibrate
  • termux-battery-status > /data/data/com.termux/files/usr/share/nginx/html/battery.json
  1. save and wait 
    1. ctrl + X
    2. Y + enter
    3. visit http://[ip address]:8080/battery.json
  2. access via url/bat.json

install jq 

$ pkg instal jq

pretty print a json file with jq : 

$ bat.json | jq '.'

create a json file with jq

$ termux-sms-list |jq .  > sms2.json

read a value from a Json file with jq 

$ jq .myvalue bat.json

https://www.howtogeek.com/529219/how-to-parse-json-files-on-the-linux-command-line-with-jq/