Sebastian 8b7bc0a650 fix(docker): run on read-only filesystems, IPv6-less hosts and cpu-limited containers (#556)
Five fixes to the Docker image, found while running it-tools on
OpenShift, where containers run as an arbitrary UID. No application code
is changed.

Start on a read-only filesystem. `docker run --read-only` and Kubernetes
readOnlyRootFilesystem crash-loop the container, because
20-envsubst-on-templates.sh checks its output directory with
`[ ! -w $dir ]`. That only reads permission bits, so a read-only mount
passes the check, the write fails with EROFS and `set -e` stops the
entrypoint. 19-skip-envsubst-if-readonly.envsh now tests the directory
with a real write and, on failure, points NGINX_ENVSUBST_TEMPLATE_DIR at
a missing path so the envsubst script exits early. That is only safe if
the config in the image is already correct, and today it is nginx's
stock welcome config, so the Dockerfile renders the template at build
time as well. Writable setups are unchanged: the write test passes,
nothing is exported and the config is rendered at startup as before, so
a custom $PORT still works.

Skip IPv6 when the host has none. nginx.conf always listens on IPv6, so
where IPv6 is off nginx fails with `socket() [::]:8080 failed (97:
Address family not supported by protocol)`.
25-remove-ipv6-listen-if-unavailable.sh comments those lines out, using
the same /proc/net/if_inet6 check as nginx's own
10-listen-on-ipv6-by-default.sh, and exits at once when IPv6 works. It
probes the directory before editing, because `sed -i` rewrites through a
temporary file there, so a writable file in a read-only directory is not
enough, and it tolerates a failed edit so it can never stop the
entrypoint.

Match workers to the cpu limit. `worker_processes auto` counts the
host's cores, not the container's cpu limit, so the image starts 256
workers on a 256-core host in any container size. `docker run -m 192m`
is enough to be OOM-killed at startup. Setting
NGINX_ENTRYPOINT_WORKER_PROCESSES_AUTOTUNE enables the script nginx
already ships. Containers without a cpu limit keep one worker per core.
This is the only change that affects a deployment that works today.

Return 404 for missing assets. All paths fall back to index.html, so a
missing build file returns 200 and text/html, and the browser reports a
confusing MIME error instead of a 404. /assets/ now skips the SPA
fallback. Sub-folder requests such as /it-tools/assets/... still match
`location /`, so those deployments do not change.

Stop remapping js. nginx.conf includes mime.types, which already maps
js, then maps it again, so every startup logs a duplicate extension
warning. mime.types has no entry for mjs, so mjs stays and js goes.

Signed-off-by: Sebastian Danielsson <sebastian.danielsson@proton.me>
2026-08-14 19:22:10 +02:00
2022-04-16 13:41:10 +02:00
2023-03-01 23:35:17 +01:00
2026-01-17 13:03:06 +01:00
2026-01-17 13:03:06 +01:00
2022-07-21 21:06:22 +02:00
2026-07-12 23:11:48 +02:00
2022-03-31 00:33:29 +02:00

BREAKING CHANGE for Container Image

Since the base image is now nginx-unpriviledged the container will now listen to port 8080 and not 80. So you need to update your port mapping, i.e. from 8080:80 to 8080:8080.

You can override listening port using environment variable PORT (docker option -e PORT=8888).

If the container needs to listen to IPv6, it needs to be enabled: https://serverfault.com/questions/1147296/how-to-enable-ipv6-on-ubuntu-20-04. Alternatively, you can mount your own nginx.conf own using docker option -v "./nginx.conf:/etc/nginx/templates/default.conf.template" (with listen [::]:8080; removed)

Build requirements

To build this project, you need around 16GB (as it builds on Github workers). Below, you will get some out of memory or node allocation failed.

PR Welcome

Especially for UI improvements and translation. And for anything else.

Want to support this fork of IT Tools: Buy me a coffee

Some tools like PGP encryption rely on WebCrypto API that is only available in HTTPS/SSL. Also, if you want to use PWA, HTTPS is required.

So even on internal installations, you should enable HTTPS using Let's Encrypt using DNS Challenge

Some docs about DNS Challenge:

Related doc for CyberPanel: https://community.cyberpanel.net/t/reverse-proxy-traffic-to-docker-container-on-cyberpanel/30644

Check out these change here: https://sharevb-it-tools.vercel.app/ or https://sharevb.github.io/it-tools/

You can use my image in your docker-compose/quadlet file if you want an up-to-date version of it-tools (with my PR and some of others) until the main branch has been updated.

(Thanks to gitmotion for this model of README fork)

Contributors

Big thanks to all the people who have already contributed!

contributors

Development under Windows

Use of WSL2 is recommended to develop using VSCode on Windows. Direct development is tricky (because of some dependencies)

Added features

Container images

GitHub Container Registry: ghcr.io/sharevb/it-tools:latest

Docker Hub: sharevb/it-tools:latest

docker run --pull always --restart unless-stopped -p 8080:8080 sharevb/it-tools:latest

Other existing docker tags: latest-en (english only)

Use in Docker Compose file

services:
  it-tools:
    container_name: it-tools
    image: sharevb/it-tools:latest
    pull_policy: always
    restart: unless-stopped
    ports:
      - 8080:8080

Use in Podman Quadlet file

[Unit]
Description=IT Tools container
After=network-online.target

[Container]
AutoUpdate=registry
Image=ghcr.io/sharevb/it-tools:latest
PublishPort=8080:8080
Label=io.containers.autoupdate=registry

[Install]
WantedBy=multi-user.target default.target

[Service]
Restart=always

Use with companion Self Hosted docker services

Some tools requires additional docker services: HTTPS/DNS tools/Ping, HTML to PDF, Docker Image Download, Multi Links Download, Short Url Expander and TCP/UDP Port tester.

See complete example here: docker-with-services

Filter tools and add home custom content

You can add custom content in Home page by mounting a home.custom.md in /usr/share/nginx/html.

You can filter available tools by mounting tools-filter.json in /usr/share/nginx/html. It can contains the following filtering regex:

{
  "excludeCategoryFilterRegex": "",
  "includeCategoryFilterRegex": "",
  "excludeToolsFilterRegex": "",
  "includeToolsFilterRegex": ""
}

Category matches on category (English) names ; Tools matches on tools path/url.

See docker-tools-filter-and-home-content

Add custom external tools

You can add custom external tools (href or markdownContent) by mounting a external-tools.json in /usr/share/nginx/html with the following structure:

[
  {
    "name": "GitHub",
    "path": "/github",
    "description": "Link to Github",
    "keywords": ["github"],
    "category": "Links",
    "href": "https://github.com"
  },
  {
    "name": "Some text",
    "path": "/some-text",
    "description": "Some description",
    "keywords": ["some"],
    "category": "Links",
    "markdownContent": "Some useful **text**\n\nin *markdown*"
  }
]

See docker-tools-filter-and-home-content

Setting default tools parameters / default UI language at runtime

For a complete sample, see docker-with-services.

You can set default tool parameters by mounting a tools-settings.json in /usr/share/nginx/html.

It is a two level json, with the first level being for tool name and the second level for parameter name:

{
  "regex-tester": {
    "multi": true,
    "regex": "some regex",
    "global": false
  }
}

You can find tool name and parameter name in the tools source code src/tools subfolder :

  • example pattern for const global = useQueryParamOrStorage({ storageName: 'regex-tester:g', name: 'global', defaultValue: true });:
{
  "regex-tester": {
    "global": false
  }
}
  • example pattern for const value = useQueryParam({ tool: 'barcode-gen', name: 'text', defaultValue: '123456789' });:
{
  "barcode-gen": {
    "text": "4356"
  }
}
  • example pattern for const width = useITStorage('ascii-text-drawer:width', 80);:
{
  "ascii-text-drawer": {
    "width": 80
  }
}

To define the default UI language, add a default_locale key to json:

{
  "default_locale": "fr"
}

To build using a custom default language:

docker build -t it-tools-fr --build-arg VITE_LANGUAGE=fr .
docker run -d --name it-tools-fr --restart unless-stopped -p 8080:8080 it-tools-fr

Build container image for a custom subfolder

According to https://github.com/sharevb/it-tools/pull/461#issuecomment-1602506049 and https://github.com/CorentinTh/it-tools/pull/461:

docker build -t it-tools  --build-arg BASE_URL="/my-folder/" .
docker run -d --name it-tools --restart unless-stopped -p 8080:8080 it-tools

Then if you go to http://localhost:8080 you'll get a blank page, but opening the DevTools (& refreshing) you'll notice in the Network tab that the app is trying to fetch assets from /my-folder/...

So you would need to put another server in front of it, like Nginx Proxy Manager, Traefik, caddy etc. Then setup a reverse proxy pass using /my-folder

Docker compose for hosting in a /it-tools/ subfolder

For /it-tools/ subfolder, you can use baseurl-it-tools tag.

See sample of docker-compose.yml and nginx.conf, this docker image needs to have another reverse proxy in front of it, like Nginx Proxy Manager, Traefik, caddy etc.

Setup a reverse proxy pass using /it-tools/. And you should be able to access it-tools in /it-tools/ of your server.

An example of nginx reverse proxy configuration is available at: https://github.com/sharevb/it-tools/tree/chore/all-my-stuffs/docker-subfolder-sample

To run the sample:

git clone https://github.com/sharevb/it-tools
cd it-tools/docker-subfolder-sample/
docker compose up

Then navigate to http://localhost:8080/it-tools/

To build using a custom folder:

  1. BASE_URL="/it-tools/" pnpm build
  2. Rename the generated dist folder to it-tools and serve on https://your-domain.com/it-tools

To build for GitHub Pages:

  1. Enable GitHub Pages build and deployment option in your fork, under Settings > Pages and select GitHub Actions as the source
  2. Add the following GitHub action to your repo: https://github.com/sharevb/it-tools/tree/chore/all-my-stuffs/.github/workflows/sharevb-github-pages-publish.yml

To add authentication

Assuming you're already hosting it-tools behind a reverse proxy, you can configure forward-auth and enforce authentication from the reverse proxy

(thanks @jogerj)

Deploy as LXC container

In Proxmox VE, you can use docker image directly:

sudo lxc-create -n sharevb-it-tools -t oci -- --url docker://ghcr.io/sharevb/it-tools:latest

Contribute

To install VSCode in WSL2 (Windows), see: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode

VSCode with the following extensions:

with the following settings:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "oxc.oxc-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.oxc": "always"
  },
  "i18n-ally.localesPaths": ["locales", "src/tools/*/locales"],
  "i18n-ally.keystyle": "nested"
}

Type Support for .vue Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need TypeScript Vue Plugin (Volar) to make the TypeScript language service aware of .vue types.

If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a Take Over Mode that is more performant. You can enable it by the following steps:

  1. Disable the built-in TypeScript Extension
    1. Run Extensions: Show Built-in Extensions from VSCode's command palette
    2. Find TypeScript and JavaScript Language Features, right click and select Disable (Workspace)
  2. Reload the VSCode window by running Developer: Reload Window from the command palette.

Project Setup

pnpm install --ignore-scripts

Compile and Hot-Reload for Development

pnpm dev

Type-Check, Compile and Minify for Production

pnpm build

Run Unit Tests with Vitest

pnpm test

Lint with Oxlint

pnpm lint

Format with Oxfmt

pnpm fmt

Ensure CI (lock, oxlint, typecheck) will succeed

Before submitting a PR, run:

pnpm install --ignore-scripts && pnpm lint:fix && pnpm typecheck

Create a new tool

To create a new tool, there is a script that generate the boilerplate of the new tool, simply run:

pnpm run script:create:tool my-tool-name

It will create a directory in src/tools with the correct files. You will need to fill src/tools/_my-tool-name_/index.ts with tool name, category, description... and then develop the tool.

Installation methods

Local installation required installing first: python3 make g++

Container Image Local Installation
GitHub Container Registry: ghcr.io/sharevb/it-tools:latest
Docker Hub: sharevb/it-tools:latest
sudo apt-get install python3 make g++ && git clone -b chore/all-my-stuffs https://github.com/sharevb/it-tools.git && cd it-tools/ && pnpm i --ignore-scripts && pnpm dev
replace your current image with this image copy & paste oneliner (from github repo)
You may need to clear cache and hard reload to get new features loading Installing packages for the first time may take some time; please wait until it finishes
logo

License

This project is under the GNU GPLv3.

S
Description
No description provided
Readme GPL-3.0
77 MiB
0 Stars 1 Watchers 0 Forks
Languages
JavaScript 42.6%
Vue 32.7%
TypeScript 23.7%
HTML 0.8%
CSS 0.1%