Knowledgebase

This guide explains the native IT Tools installation used by the Sive AppStore image. It helps administrators understand, maintain, back up, update, and troubleshoot the service after deployment. IT Tools is delivered as a prebuilt static web application and served directly by Nginx; it does not require a database, a Node.js server process, or a container runtime.

Architecture and important paths

• Web application: /var/www/it-tools
• Nginx virtual host: /etc/nginx/sites-available/ittools
• Enabled-site link: /etc/nginx/sites-enabled/ittools
• Nginx logs: /var/log/nginx/access.log and /var/log/nginx/error.log

There is no application database or background worker to maintain. Nginx serves the HTML, JavaScript, stylesheets, icons, and fonts. Application processing is performed in the visitor's browser.

Before you begin

Run these commands as root on Ubuntu 24.04 LTS x86_64. Replace tools.example.com with the hostname that points to your server. Confirm the DNS record before requesting a TLS certificate.

If IT Tools is already installed, complete the backup procedure before replacing /var/www/it-tools.

1. Install the required packages

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
  ca-certificates curl nginx qemu-guest-agent unzip \
  certbot python3-certbot-nginx ufw

systemctl enable --now nginx
systemctl enable --now qemu-guest-agent || true

No PHP, Node.js, database server, Docker, or Podman package is needed for the application itself.

2. Download and verify the pinned release

The reference deployment uses the exact version and checksum below. Checksum verification is mandatory; stop immediately if sha256sum reports a mismatch.

ITTOOLS_VERSION="2024.10.22-7ca5933"
ITTOOLS_ARCHIVE="it-tools-${ITTOOLS_VERSION}.zip"
ITTOOLS_URL="https://github.com/CorentinTh/it-tools/releases/download/v${ITTOOLS_VERSION}/${ITTOOLS_ARCHIVE}"
ITTOOLS_SHA256="eef276d675db6053bdc65cd8482a566785561c70eed5035a0e05b0e627b0989d"
WORK_DIR="$(mktemp -d /var/www/ittools-install.XXXXXX)"

curl -fL --retry 4 --retry-delay 3 \
  -o "${WORK_DIR}/${ITTOOLS_ARCHIVE}" "${ITTOOLS_URL}"
printf '%s  %s\n' "${ITTOOLS_SHA256}" "${WORK_DIR}/${ITTOOLS_ARCHIVE}" \
  | sha256sum -c -

3. Check and extract the archive safely

Reject an archive containing absolute paths or parent-directory traversal before extracting it:

if unzip -Z1 "${WORK_DIR}/${ITTOOLS_ARCHIVE}" \
  | grep -Eq '(^/|(^|/)\.\.(/|$))'; then
  echo "The IT Tools archive contains an unsafe path" >&2
  exit 1
fi

install -d -m 0755 "${WORK_DIR}/extract"
unzip -q "${WORK_DIR}/${ITTOOLS_ARCHIVE}" -d "${WORK_DIR}/extract"

Validate the expected production bundle before publishing it:

test -f "${WORK_DIR}/extract/dist/index.html"
test -f "${WORK_DIR}/extract/dist/assets/index-f8ba620c.js"
grep -Fq "IT Tools - Handy online tools for developers" \
  "${WORK_DIR}/extract/dist/index.html"

The fingerprinted JavaScript filename is specific to this pinned release. When deliberately installing another release, confirm its expected files from that release rather than blindly reusing this check.

4. Install the static application

For a first installation:

test ! -e /var/www/it-tools
mv "${WORK_DIR}/extract/dist" /var/www/it-tools
chown -R root:root /var/www/it-tools
find /var/www/it-tools -type d -exec chmod 0755 {} +
find /var/www/it-tools -type f -exec chmod 0644 {} +

Root ownership prevents the web-server account from modifying executable browser assets. Nginx needs only read and directory-traversal access.

5. Configure Nginx

Create /etc/nginx/sites-available/ittools:

server {
    listen 80;
    listen [::]:80;
    server_name tools.example.com;
    root /var/www/it-tools;
    index index.html;
    charset utf-8;
    server_tokens off;

    add_header X-IT-TOOLS-VERSION "2024.10.22-7ca5933" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Permissions-Policy "camera=(self), microphone=(self), geolocation=()" always;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location = /index.html {
        expires -1;
        add_header Cache-Control "no-cache";
        add_header X-IT-TOOLS-VERSION "2024.10.22-7ca5933" always;
        add_header X-Content-Type-Options "nosniff" always;
    }

    location = /sw.js {
        try_files $uri =404;
        expires -1;
        add_header Cache-Control "no-cache";
        add_header X-Content-Type-Options "nosniff" always;
    }

    location ~* \.(?:css|js|png|jpg|jpeg|gif|ico|svg|webp|woff2?|ttf)$ {
        try_files $uri =404;
        expires 1y;
        add_header Cache-Control "public, immutable";
        add_header X-Content-Type-Options "nosniff" always;
    }

    location ~ /\. {
        deny all;
    }
}

The fallback to index.html supports client-side routes. The HTML entry point and service worker are deliberately not cached, while fingerprinted assets receive long-lived immutable caching.

ln -sfn /etc/nginx/sites-available/ittools \
  /etc/nginx/sites-enabled/ittools
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl restart nginx

6. Enable HTTPS and the firewall

After tools.example.com resolves to the server:

certbot --nginx -d tools.example.com

ufw allow OpenSSH
ufw allow 'Nginx Full'
ufw enable

Confirm that Certbot configured the intended virtual host and that HTTP redirects to HTTPS. Test renewal without changing the live certificate:

certbot renew --dry-run

7. Verify the deployment

curl -fsSI https://tools.example.com/
curl -fsS https://tools.example.com/ \
  | grep -F "IT Tools - Handy online tools for developers"
curl -fsS -D - -o /dev/null \
  -H 'Host: tools.example.com' http://127.0.0.1/ \
  | grep -Fi 'X-IT-TOOLS-VERSION: 2024.10.22-7ca5933'

systemctl is-active nginx
nginx -t

A healthy installation returns HTTP 200, contains the expected page title, sends the pinned version header, and passes the Nginx configuration test.

Routine maintenance

• Install Ubuntu security updates regularly and reboot when required.
• Monitor Nginx with systemctl status nginx and journalctl -u nginx.
• Review the Nginx access and error logs for unusual traffic or missing assets.
• Run certbot renew --dry-run after certificate or Nginx changes.
• Monitor free disk space, although the static application itself has no growing database.
• Repeat the HTTP, title, and version-header checks after every change.

Backups and restoration

IT Tools has no server-side user database. Back up the deployed release and its web-server configuration:

• /var/www/it-tools
• /etc/nginx/sites-available/ittools
• The relevant files under /etc/letsencrypt, preserving their restrictive permissions

Example:

BACKUP_DIR="/root/ittools-backup-$(date +%F-%H%M%S)"
install -d -m 0700 "${BACKUP_DIR}"
tar -C / -czf "${BACKUP_DIR}/ittools-files.tar.gz" \
  var/www/it-tools \
  etc/nginx/sites-available/ittools
cp -a /etc/letsencrypt "${BACKUP_DIR}/letsencrypt"
chmod -R go-rwx "${BACKUP_DIR}"

Copy backups off the server. To restore, extract the saved application directory and Nginx configuration, restore root ownership and the permissions described above, run nginx -t, reload Nginx, and repeat all health checks.

Updating IT Tools

Read the release notes before updating. Obtain the intended release from the official project and independently verify its checksum. Do not reuse the checksum from version 2024.10.22-7ca5933 for a different archive.

1. Take a backup and verify that it can be read.
2. Download the new release into a temporary directory.
3. Verify its checksum and reject unsafe archive paths.
4. Extract and validate dist/index.html and the release's fingerprinted assets.
5. Keep the old application directory while switching to the new one.
6. Update the X-IT-TOOLS-VERSION values in Nginx.
7. Test Nginx, reload it, and repeat all application checks.

Example switch after validating a new dist directory:

PREVIOUS="/var/www/it-tools.previous-$(date +%F-%H%M%S)"
mv /var/www/it-tools "${PREVIOUS}"
mv "${WORK_DIR}/extract/dist" /var/www/it-tools
chown -R root:root /var/www/it-tools
find /var/www/it-tools -type d -exec chmod 0755 {} +
find /var/www/it-tools -type f -exec chmod 0644 {} +
nginx -t
systemctl reload nginx

Keep ${PREVIOUS} until the new release works in a private browser window and its service worker has updated. If validation fails, move the failed directory aside, restore ${PREVIOUS}, restore the matching Nginx version header, and reload Nginx.

Troubleshooting

The site returns 404 or the Nginx welcome page

readlink -f /etc/nginx/sites-enabled/ittools
test -f /var/www/it-tools/index.html
nginx -T | grep -A8 -B2 'server_name tools.example.com'
nginx -t
systemctl status nginx --no-pager

Confirm that the enabled link targets the IT Tools virtual host, the DNS hostname matches server_name, and the default site is not handling the request.

A tool route works from navigation but fails after refresh

Ensure the root location still contains try_files $uri $uri/ /index.html;. This fallback is required for client-side routes.

The browser shows an older release after an update

First compare the X-IT-TOOLS-VERSION response header with the intended release. Then use a private window or clear the site's storage and service worker. Verify that /index.html and /sw.js return Cache-Control: no-cache; only fingerprinted static assets should be immutable.

curl -fsSI https://tools.example.com/
curl -fsSI https://tools.example.com/sw.js

Assets return 403

namei -l /var/www/it-tools/index.html
find /var/www/it-tools -type d ! -perm -0005 -print
find /var/www/it-tools -type f ! -perm -0004 -print

Restore root ownership, directory mode 0755, and file mode 0644. Do not make the application tree writable by the Nginx worker merely to solve a read-permission problem.

TLS issuance or renewal fails

getent hosts tools.example.com
ss -ltnp | grep -E ':(80|443)\s'
ufw status
certbot certificates
journalctl -u nginx -n 100 --no-pager

Check public DNS, inbound ports 80 and 443, the Nginx configuration, and certificate rate-limit messages before retrying.

Nginx configuration fails after editing

nginx -t
journalctl -u nginx -n 100 --no-pager
diff -u /root/ittools.conf.known-good \
  /etc/nginx/sites-available/ittools

Do not reload Nginx until nginx -t succeeds. Restore the most recent known-good virtual-host backup if necessary.