Skip to content

refactor(deploy): simplify runtime configuration#355

Open
seebeen wants to merge 1 commit intoidank:masterfrom
seebeen:feat/docker-image
Open

refactor(deploy): simplify runtime configuration#355
seebeen wants to merge 1 commit intoidank:masterfrom
seebeen:feat/docker-image

Conversation

@seebeen
Copy link
Copy Markdown

@seebeen seebeen commented Apr 14, 2026

This PR refactors the deployment/runtime setup for explainshell and simplifies how the web app is configured in local and container
environments.

The Dockerfile and Docker entrypoint were written by me.
The Python-side runtime/config/logging changes were implemented with assistance from OpenAI Codex. 5.4 high effort.

What Changed

  • switched the image to a multi-stage Docker build
  • split Python dependency install, DB download/decompression, and runtime into separate stages
  • made the baked SQLite DB independently cacheable via DB_CACHE_BUST
  • moved container startup logic from start.sh to docker/docker-entrypoint.sh
  • changed the app/container port from 8080 to 5000
  • switched the DB download step from wget to curl
  • made Gunicorn access logging env-driven and disabled by default
  • kept app logging at INFO by default via LOG_LEVEL
  • moved web logging bootstrap into the Flask app factory
  • made create_app() resolve runtime config from env vars directly instead of shell-rendered Python arguments
  • changed runserver.py to bind to 127.0.0.1 by default for local development
  • added regression coverage for app-factory env handling and local runserver binding
  • updated README and AGENTS docs for the new runtime/config behavior

Goals

Primary:

  • reduce and stabilize Docker rebuild time
  • simplify runtime configuration
  • remove shell/Python coupling in the Gunicorn startup path

Secondary:

  • make the baked DB layer cache separately from app code
  • make local development defaults safer
  • clean up logging behavior between local dev and container execution

Runtime / Env Changes

New or clarified runtime behavior:

  • PORT defaults to 5000
  • local runserver.py binds to 127.0.0.1 by default
  • HOST_IP can still override the bind address
  • LOG_LEVEL controls explainshell.* app logs and defaults to INFO
  • GUNICORN_ACCESS_LOG enables Gunicorn access logs when set to 1 or true
  • GUNICORN_ACCESS_LOG_FILE and GUNICORN_ACCESS_LOG_FORMAT are available when access logging is enabled
  • DB_PATH is resolved inside the app factory/runtime instead of being passed via shell-rendered Python args

If a Docker Hub account is created and linked for this project, I can add a multi-arch container publishing workflow as a follow-up.

Looking forward to your feedback.

@idank
Copy link
Copy Markdown
Owner

idank commented Apr 15, 2026

Hi @seebeen , thanks for the PR!

  1. What's the motivation for this change? Specifically the Dockerfile, is there any gain?
  2. Since you mentioned this was AI authored, can you share the prompt? I ran this through claude's /review and there are some obvious things to fix. Maybe make another pass. :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants