SHS Tools is an internal-only, authentication-free FastAPI utility portal for practical file and text processing.

• Python: 3.10 or newer. This workspace was checked with Python 3.10.10.
• Node.js: not required for the current project.
• External binaries: ffmpeg, ffprobe, and yt-dlp must be available to the app. yt-dlp is also installed from requirements.txt.

• Shared plugin-style execution pipeline
• Generic catalog and tool detail pages
• File-based job storage with per-job isolation
• Result pages and downloads by job_id
• Initial tools:
  • PDF merge, split, rotate
  • Image convert, resize, compress
  • Media sample, video trim, video convert
  • ZIP create, extract
  • Audio convert, audio extract
  • Text cleanup / newline normalization

1. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install Python dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt

3. Create a local environment file and edit it:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

4. Start the app:

python run.py

5. Open http://127.0.0.1:8002.

The app reads environment variables from .env through pydantic-settings. Keep real .env files out of Git.

Important settings:

• SHS_TOOLS_HOST and SHS_TOOLS_PORT: bind address and port for python run.py.
• SHS_TOOLS_DEBUG: set to false in production.
• SHS_TOOLS_INTERNAL_BASE_URL: base URL used by internal app links.
• SHS_TOOLS_JOB_RETENTION_HOURS: how long job files are retained before cleanup.
• SHS_TOOLS_RUNTIME_FILE_RETENTION_HOURS: how long orphaned temp, upload, output, log, and cache files are retained before cleanup.
• SHS_TOOLS_MAX_UPLOAD_SIZE_MB, SHS_TOOLS_MAX_FILE_COUNT, SHS_TOOLS_MAX_TEXT_LENGTH: request limits.
• SHS_TOOLS_FFMPEG_BINARY, SHS_TOOLS_FFPROBE_BINARY, SHS_TOOLS_YT_DLP_BINARY: executable names or absolute paths.
• SHS_TOOLS_QUEUE_*: background queue behavior and concurrency limits.

There is no database and no migration command for the current project. Runtime files are stored under app/data/:

• app/data/jobs/: job metadata, uploaded inputs, work files, and outputs.
• app/data/temp/: temporary analysis files.
• app/data/uploads/ and app/data/outputs/: reserved runtime storage.

These directories are created automatically at runtime and are ignored by Git.

Application logs are written to stdout/stderr. Under systemd, view them with journalctl; the app does not currently create its own log files. Cache files are not created by the current code, but app/data/cache/ is included in cleanup if it exists.

The app runs runtime cleanup once on startup. For production, also run the cleanup script on a schedule so old job files do not wait for an app restart.

Preview cleanup candidates without deleting anything:

python scripts/cleanup_jobs.py --dry-run

Delete expired and stale runtime files:

python scripts/cleanup_jobs.py

Cleanup removes only paths inside app/data/ and refuses to delete runtime root directories such as app/data/, app/data/jobs/, app/data/temp/, app/data/uploads/, and app/data/outputs/.

Use a systemd oneshot service for scheduled cleanup. Create /etc/systemd/system/shs-tools-cleanup.service:

[Unit]
Description=Clean SHS Tools runtime files

[Service]
Type=oneshot
User=shs-tools
Group=shs-tools
WorkingDirectory=/opt/shs-tools
ExecStart=/opt/shs-tools/.venv/bin/python /opt/shs-tools/scripts/cleanup_jobs.py

Create /etc/systemd/system/shs-tools-cleanup.timer:

[Unit]
Description=Run SHS Tools runtime cleanup hourly

[Timer]
OnCalendar=hourly
Persistent=true

[Install]
WantedBy=timers.target

Enable the timer and check cleanup logs:

sudo systemctl daemon-reload
sudo systemctl enable --now shs-tools-cleanup.timer
sudo systemctl list-timers shs-tools-cleanup.timer
sudo journalctl -u shs-tools-cleanup -f

Example target path for the shs-tools VM:

sudo mkdir -p /opt/shs-tools
sudo chown "$USER":"$USER" /opt/shs-tools
git clone <GITHUB_REPOSITORY_URL> /opt/shs-tools
cd /opt/shs-tools

Install system packages on Debian/Ubuntu:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip ffmpeg

Create the virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Create .env:

cp .env.example .env
nano .env

Recommended production values:

SHS_TOOLS_HOST=0.0.0.0
SHS_TOOLS_PORT=8002
SHS_TOOLS_DEBUG=false
SHS_TOOLS_INTERNAL_BASE_URL=http://<vm-ip-or-domain>:8002

Run once in the foreground for a quick smoke test:

python run.py

For a direct production process without systemd:

SHS_TOOLS_DEBUG=false .venv/bin/python run.py

Create a service user, or replace User and Group below with the deployment account that owns /opt/shs-tools:

sudo useradd --system --home /opt/shs-tools --shell /usr/sbin/nologin shs-tools
sudo chown -R shs-tools:shs-tools /opt/shs-tools

Create /etc/systemd/system/shs-tools.service:

[Unit]
Description=SHS Tools FastAPI service
After=network.target

[Service]
Type=simple
User=shs-tools
Group=shs-tools
WorkingDirectory=/opt/shs-tools
ExecStart=/opt/shs-tools/.venv/bin/python /opt/shs-tools/run.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now shs-tools

Check status and logs:

sudo systemctl status shs-tools
sudo journalctl -u shs-tools -f

• Routes stay generic.
• Most tools use the shared tool_detail.html page.
• Tool execution always flows through the shared runner.
• New tools should normally need:
  • one executor
  • one tool definition
  • one registry entry

1. Create an executor under app/tools/<category>/.
2. Define the tool metadata on the executor.
3. Register the tool in app/tools/definitions.py.
4. Add any new library dependency if needed.

If a tool truly needs a visual workflow, add a custom template and frontend assets, but keep execution on POST /tools/{tool_id}/run.