Bug: New deployment, account creation fails

[tturnerdev]

Description

First-time user to Litestar. Testing by trying to deploy the fullstack demo.

Multiple failures requiring troubleshooting:

1. Postgres port in .env.local.example should match docker at 15432
2. Inconsistencies between README.md and AGENTS.md (AGENTS.md doesn't include app database upgrade, and uses uv run app run instead of app run, which is correct?)
3. Tests fail out of the box, appears to be missing email templates

(3) Failed tests (make test):

Results (9.77s):
     285 passed
      11 failed
         - src/py/tests/unit/lib/test_email_service.py:106 test_send_verification_email_without_name
         - src/py/tests/unit/lib/test_email_service.py:200 test_verification_email_content_structure
         - src/py/tests/unit/lib/test_email_service.py:171 test_send_password_reset_confirmation_email
         - src/py/tests/unit/lib/test_email_service.py:140 test_send_welcome_email
         - src/py/tests/unit/lib/test_email_service.py:274 test_template_caching
         - src/py/tests/unit/lib/test_email_service.py:120 test_send_verification_email_url_construction
         - src/py/tests/unit/lib/test_email_service.py:91 test_send_verification_email_with_name
         - src/py/tests/unit/lib/test_email_service.py:223 test_verification_email_security_considerations
         - src/py/tests/unit/lib/test_email_service.py:260 test_template_rendering
         - src/py/tests/unit/lib/test_email_service.py:182 test_send_team_invitation_email
         - src/py/tests/unit/lib/test_email_service.py:153 test_send_password_reset_email
     337 error
✓ Tests passed ✨

(3) May be related: #51

Found the below which referenced building email templates before CI tests so ran all the make ... commands I could find:
32b77af

make build-emails
make build-assets
make build-wheel

Now I get (green) account creation success notification in-app and no apparent errors in console run output.

However, many more errors when running make test, most (all?) appear to be TypeError: list indices must be integers or slices, not str

$ make test
...
FAILED src/py/tests/integration/teams/services/test_team_service.py::test_get_nonexistent_team - TypeError: list indices must be integers or slices, not str
FAILED src/py/tests/integration/teams/services/test_team_service.py::test_create_team_empty_name - TypeError: list indices must be integers or slices, not str
FAILED src/py/tests/integration/teams/services/test_team_service.py::test_team_with_multiple_members_and_tags - TypeError: list indices must be integers or slices, not str

Results (8.82s):
     296 passed
     337 error
✓ Tests passed ✨

I'll update this as I find more while walking through quick start.

MCVE

make install
cp .env.local.example .env
make start-infra
app database upgrade
uv run app run

Steps to reproduce

Screenshots

No response

Logs

Package Version

Loading environment configuration from .env
Using Litestar Fullstack Template app from env: 'app.server.asgi:create_app'
Starting Granian server process with uvloop ──────────────────────────────────────────────────────────────────────────────────────────
┌──────────────────────────────┬────────────────────────────────────────────────────────┐
│ Litestar version             │ 2.19.0                                                 │
│ Debug mode                   │ Enabled                                                │
│ Python Debugger on exception │ Disabled                                               │
│ CORS                         │ Enabled                                                │
│ CSRF                         │ Disabled                                               │
│ OpenAPI                      │ Enabled path=/schema                                   │
│ Compression                  │ Disabled                                               │
│ Middlewares                  │ JWTCookieAuthenticationMiddleware, ViteProxyMiddleware │
└──────────────────────────────┴────────────────────────────────────────────────────────┘
• Applied Vite environment variables
✓ Types exported → openapi: src/js/web/src/lib/generated/openapi.json
• Starting Vite server with HMR
✓ Vite process started
2026-01-23T03:07:11.507215Z [info     ] Starting granian (main PID: 25258)
2026-01-23T03:07:11.509451Z [info     ] Listening at: http://0.0.0.0:8000
2026-01-23T03:07:11.511762Z [info     ] Spawning worker-1 with PID: 25264
$ vite
✓ SPA handler initialized
2026-01-23T03:07:11.664248Z [info     ] Discovered domain components   by_domain={'accounts': ['AccessController', 'EmailVerificationController', 'MfaChallengeController', 'MfaController', 'OAuthAccountController', 'OAuthController', 'ProfileController', 'RoleController', 'UserController', 'UserRoleController'], 'admin': ['AdminTeamsController', 'AdminUsersController', 'AuditController', 'DashboardController'], 'system': ['SystemController'], 'tags': ['TagController'], 'teams': ['TeamController', 'TeamInvitationController', 'TeamMemberController']} controllers=19 repositories=0 schemas=63 services=12 signals=6
2026-01-23T03:07:11.665671Z [info     ] Started worker-1
2026-01-23T03:07:11.665886Z [info     ] Started worker-1 runtime-1
[litestar-vite] Configuration mismatch detected:
  • bundleDir: vite.config.ts="home/static/dev-wsl/admin-portal/src/py/app/server/static/web" differs from Python="../../py/app/server/static/web"

Precedence: vite.config.ts > .litestar.json > defaults
See: https://docs.litestar.dev/vite/config-precedence

• Watching: openapi.json
• Generating TypeScript types...
• openapi-ts config: openapi-ts.config.ts
• Schema types (unchanged)
✓ TypeScript artifacts updated (1058ms)

  VITE v7.3.1  ready in 1769 ms

  ➜  Local:   http://localhost:3006/static/
  ➜  Network: http://10.255.255.254:3006/static/
  ➜  Network: http://172.18.100.8:3006/static/

  LITESTAR 2.19.0

  ➜  Mode:       SPA (index.html)
  ➜  App URL:    http://localhost:8000 ✓
  ➜  Dev Server: http://localhost:3006
  ➜  Type Gen:   src/lib/generated/

Platform

• Linux
• Mac
• Windows
• Other (Please specify in the description above)

[tturnerdev]

Latest commit with clean-up work looks great, but doesn't appear to address this issue.

I just pulled lastest and ran following commands:

git clone git clone git@github.com:tturnerdev/litestar-fullstack.git
cd litestar-fullstack
make install
cp .env.local.example .env && vim .env # Fill out variables as required in docs
make start-infra # Deploy resources locally in Docker
uv run app database upgrade
VITE_DEV_MODE=true # For debug
uv run app run

(Note: specifically, make build is never called separately)

App starts great, but when choosing "Try the demo" and attempting to create an account, there is a green "success" toast/notification, but console shows same python error related to the missing email templates:

2026-01-31T01:10:25.278940Z [info     ] Started worker-1 runtime-1
• Watching: openapi.json
• Generating TypeScript types...
• openapi-ts config: openapi-ts.config.ts
• Schema types (unchanged)
• Static props types (unchanged)
✓ TypeScript artifacts updated (1227ms)

  VITE v7.3.1  ready in 1939 ms

  ➜  Local:   http://localhost:3006/static/
  ➜  Network: http://10.255.255.254:3006/static/
  ➜  Network: http://172.18.100.8:3006/static/

  LITESTAR 2.19.0

  ➜  Mode:       SPA (index.html)
  ➜  App URL:    http://localhost:8000 ✓
  ➜  Dev Server: http://localhost:3006
  ➜  Type Gen:   src/lib/generated/

2026-01-31T02:21:11.187214Z [info     ] Running post signup flow.
2026-01-31T02:21:11.209649Z [info     ] Found user                     avatar_url=None created_at=datetime.datetime(2026, 1, 31, 2, 21, 11, 173133, tzinfo=zoneinfo.ZoneInfo(key='Etc/UTC')) email=test.tester@example.com failed_reset_attempts=0 id=UUID('019c11da-b285-7ef2-bc42-30d6b26cde72') is_active=True is_superuser=False is_two_factor_enabled=False is_verified=False joined_at=datetime.date(2026, 1, 31) login_count=0 name=Test password_reset_at=None phone=None reset_locked_until=None two_factor_confirmed_at=None updated_at=datetime.datetime(2026, 1, 31, 2, 21, 11, 173138, tzinfo=zoneinfo.ZoneInfo(key='Etc/UTC')) username=None verified_at=None
2026-01-31T02:21:11.225639Z [error    ] Error while executing listener user_created_event_handler: [Errno 2] No such file or directory: '/home/static/dev-wsl/litestar-fullstack/src/py/app/server/static/email/email-verification.html'
Traceback (most recent call last):
  File "/home/static/dev-wsl/litestar-fullstack/.venv/lib/python3.13/site-packages/litestar/events/listener.py", line 73, in wrapped
    await fn(*args, **kwargs)
  File "/home/static/dev-wsl/litestar-fullstack/src/py/app/domain/accounts/listeners.py", line 46, in user_created_event_handler
    await mailer.send_verification_email(cast("UserProtocol", user), verification_token)
  File "/home/static/dev-wsl/litestar-fullstack/src/py/app/lib/email/service.py", line 155, in send_verification_email
    html_content = self._render_template(
        "email-verification.html",
    ...<4 lines>...
        },
    )
  File "/home/static/dev-wsl/litestar-fullstack/src/py/app/lib/email/service.py", line 92, in _render_template
    html = self._load_template(template_name)
  File "/home/static/dev-wsl/litestar-fullstack/src/py/app/lib/email/service.py", line 87, in _load_template
    html = template_path.read_text(encoding="utf-8")
  File "/home/static/.local/share/uv/python/cpython-3.13.7-linux-x86_64-gnu/lib/python3.13/pathlib/_local.py", line 546, in read_text
    return PathBase.read_text(self, encoding, errors, newline)
           ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/static/.local/share/uv/python/cpython-3.13.7-linux-x86_64-gnu/lib/python3.13/pathlib/_abc.py", line 632, in read_text
    with self.open(mode='r', encoding=encoding, errors=errors, newline=newline) as f:
         ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/static/.local/share/uv/python/cpython-3.13.7-linux-x86_64-gnu/lib/python3.13/pathlib/_local.py", line 537, in open
    return io.open(self, mode, buffering, encoding, errors, newline)
           ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '/home/static/dev-wsl/litestar-fullstack/src/py/app/server/static/email/email-verification.html'

I'm not sure if the email templates are static or supposed to be generated during initialization (i.e. during make install). From other commits and looking at Makefile, it appears there is logic for building the email templates (i.e. make build calls make build-emails, etc).

So may just be a quick fix of needing to update make install to call make build or update the docs to state requirement of running make build or adding make build to the make install? Or maybe I'm missing some link here.

Looks like all the logic is there, I think build-emails just needs to be wired up and called from make install.