Spaces:

cmboulanger
/

pdf-tei-editor

Build error

--restart: Kill any existing server on the port and start a new one
Host and port can be specified via arguments or environment variables:
- bin/start-dev localhost 8000
- HOST=localhost PORT=8000 bin/start-dev

Environment Variables

HOST: Server host (default: localhost)
PORT: Server port (default: 8000)
DISABLE_RELOAD: Disable auto-reload on Unix/Mac (values: 1, true, yes)
ENABLE_RELOAD: Enable auto-reload on Windows (values: 1, true, yes) - see Windows section below
FASTAPI_ALLOW_ANONYMOUS_ACCESS: Bypass authentication for development/testing (values: true)

Auto-Reload Behavior

Unix/Linux/macOS

Auto-reload is enabled by default on Unix-based systems. The server uses uvicorn's --reload flag with watchfiles to detect file changes and automatically restart.

File changes are detected via native file system events
Server restarts automatically when Python files change
Output is logged to log/fastapi-server.log and displayed in the terminal

To disable auto-reload on Unix:

DISABLE_RELOAD=true npm run start:dev

Windows

Auto-reload is disabled by default on Windows due to a known issue with uvicorn's watchfiles library.

The Windows Auto-Reload Problem

Uvicorn's file watching system has a bug on Windows where:

File changes are detected correctly
The server shuts down as expected
The server never restarts - it remains shut down

This is a known upstream issue:

Workaround for Windows

Manual Restart After Changes

On Windows, after making code changes, restart the server manually:

npm run start:dev -- --restart

The --restart flag will:

Find the process using port 8000 (via netstat -ano)
Kill it (via taskkill /F /PID)
Start a new server instance

Experimental: Enable Auto-Reload on Windows

You can try enabling auto-reload on Windows (not recommended):

ENABLE_RELOAD=true npm run start:dev

However, you'll likely encounter the shutdown-without-restart issue described above.

Platform-Specific Process Management

The development server includes platform-specific implementations for managing server processes:

Finding Processes on Ports

Windows (fastapi_app/lib/utils/server_startup.py:53-65):

netstat -ano

Parses output to find PIDs listening on specific ports.

Unix/Linux/macOS (fastapi_app/lib/utils/server_startup.py:67-75):

lsof -ti :8000

Directly returns the PID using the port.

Killing Processes

Windows (fastapi_app/lib/utils/server_startup.py:95-97):

taskkill /F /PID <pid>

Unix/Linux/macOS (fastapi_app/lib/utils/server_startup.py:99-100):

kill <pid>

Server Startup Process

The development server startup process (bin/start-dev):

Load environment variables from .env if present
Check for --restart flag and remove from arguments
Determine host and port from environment or CLI args
Check if port is in use:
- If already running and no --restart: Show "already running" message and exit
- If already running with --restart: Kill the existing process
Set up logging directory and file
Determine auto-reload setting based on platform:
- Windows: Disabled by default
- Unix/Mac: Enabled by default
Build uvicorn command with appropriate flags
Start uvicorn with output streaming to both console and log file

Uvicorn Configuration

The development server uses these uvicorn settings:

cmd = [
    'uv', 'run', 'uvicorn',
    'run_fastapi:app',
    '--host', host,
    '--port', str(port),
    '--log-level', 'info',
    '--timeout-graceful-shutdown', '1',  # Force reload after 1 second if connections don't close
    '--reload-delay', '0.25'  # Debounce rapid file changes
]

# Add --reload flag if enabled
if not disable_reload:
    cmd.insert(3, '--reload')

Logging

Server output is logged to log/fastapi-server.log on all platforms. The script uses subprocess.Popen to capture stdout/stderr and stream it to both:

The console (for real-time monitoring)
The log file (for historical reference)

Troubleshooting

Port Already in Use

If you see "port already in use" errors:

# Check what's using the port
netstat -ano | findstr :8000    # Windows
lsof -ti :8000                   # Unix/Mac

# Restart the server (kills existing and starts new)
npm run start:dev -- --restart

Server Not Starting on Windows

Check if Python/uvicorn processes are stuck:
```
tasklist | findstr python
```
Kill stuck processes:
```
taskkill /F /IM python.exe
```
Start fresh:
```
npm run start:dev
```

Auto-Reload Not Working

On Windows: This is expected behavior. Use npm run start:dev -- --restart after changes.

On Unix/Mac:

Check that watchfiles is installed: uv pip list | grep watchfiles
Check the log file for errors: cat log/fastapi-server.log
Try disabling and re-enabling: DISABLE_RELOAD=true npm run start:dev

Development Workflow

Recommended Workflow on Windows

Start the server:
```
npm run start:dev
```
Make code changes
Restart the server:
```
npm run start:dev -- --restart
```
Repeat steps 2-3

Recommended Workflow on Unix/Mac

Start the server (auto-reload enabled):
```
npm run start:dev
```
Make code changes - server restarts automatically
Watch the console for reload confirmations

Development Server

Starting the Development Server

Basic Usage

Command-Line Options