From 8db1029517923fb2244535e7f639d24d0efb0c1b Mon Sep 17 00:00:00 2001 From: cclohmar Date: Mon, 16 Mar 2026 19:11:12 +0000 Subject: [PATCH] feat: add OAuth dropdown to admin navigation and update README - Add OAuth dropdown menu in admin UI with links to Clients, Tokens, Users - Update README with install.sh details and simplified port configuration - Remove references to deleted fix scripts - Update systemd service example to show dynamic port configuration - Clarify OAuth admin UI accessibility in documentation --- README.md | 97 ++++++++++++--------------- app/modules/admin/templates/base.html | 10 +++ 2 files changed, 53 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index a15b19c..2461b3c 100644 --- a/README.md +++ b/README.md @@ -96,6 +96,8 @@ mockapi/ 5. **Initialize the database** (tables are created automatically on first run). +**For production deployment**, consider using the automated `install.sh` script which handles virtual environment creation, dependency installation, secure credential generation, and systemd service setup. See [Production Deployment with install.sh](#production-deployment-with-installsh) for details. + ## Running the Application ### Development (with auto‑reload) @@ -245,12 +247,14 @@ Default scopes include: ### Admin OAuth2 Management -Access OAuth2 management via the admin interface: +Access OAuth2 management via the admin interface navigation (OAuth dropdown): - **Clients**: `http://localhost:8000/admin/oauth/clients` – Register and manage OAuth clients -- **Tokens**: `http://localhost:8000/admin/oauth/tokens` – View and revoke issued tokens +- **Tokens**: `http://localhost:8000/admin/oauth/tokens` – View and revoke issued tokens - **Users**: `http://localhost:8000/admin/oauth/users` – Manage OAuth user records +**Admin UI Navigation**: The admin interface now includes an "OAuth" dropdown menu in the top navigation bar with direct access to Clients, Tokens, and Users management pages. + ## Production Deployment Considerations ### 1. **Environment Configuration** @@ -273,38 +277,49 @@ User=www-data Group=www-data WorkingDirectory=/path/to/mockapi Environment="PATH=/path/to/mockapi/venv/bin" -ExecStart=/path/to/mockapi/venv/bin/waitress-serve --host=0.0.0.0 --port=8000 wsgi:wsgi_app +EnvironmentFile=/path/to/mockapi/.env +# HOST and PORT are read from .env file at runtime +ExecStart=/path/to/mockapi/venv/bin/waitress-serve --host=$HOST --port=$PORT wsgi:wsgi_app Restart=always RestartSec=10 +# Security hardening +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ReadWritePaths=/path/to/mockapi + [Install] WantedBy=multi-user.target ``` -### 3. **Changing Port Configuration** -If you need to change the port MockAPI runs on (e.g., due to port conflicts), you have two options: +**Note**: The `install.sh` script automatically creates an optimized systemd service file with dynamic port configuration, security hardening, and proper environment variable loading from `.env`. + +### 3. **Production Deployment with install.sh** +For production deployments, use the provided `install.sh` script which handles all setup automatically: -#### Option A: Using the Change Port Script (Recommended) ```bash -# Download the script if not already present cd /opt/mockapi -sudo wget -O change_port.sh https://raw.githubusercontent.com/your-repo/main/change_port.sh -sudo chmod +x change_port.sh - -# Run the script -sudo bash change_port.sh +sudo ./install.sh ``` -The script will: -1. Show current port configuration -2. Ask for new port number -3. Update `.env` file -4. Update systemd service file -5. Update OAuth2 issuer URL -6. Restart the service +The install script will: +1. Check Python version and handle Python 3.13+ compatibility +2. Create Python virtual environment with required dependencies +3. Generate secure credentials (admin password, secret key) +4. Create `.env` configuration file with all required variables +5. Initialize the database +6. Create and configure systemd service with dynamic port configuration +7. Start and enable the service -#### Option B: Manual Port Change -If you prefer to change the port manually: +**Key Features**: +- **Python 3.13.5+ compatibility**: Automatically handles SQLAlchemy 2.0.27+ requirements +- **Dynamic port configuration**: Service reads HOST/PORT from `.env` file at runtime +- **Secure credential generation**: Random admin password and secret key +- **Missing variable protection**: Automatically adds required environment variables if missing + +### 4. **Changing Port Configuration** +Port configuration is now simplified - all settings are read from the `.env` file: 1. **Edit the `.env` file**: ```bash @@ -317,49 +332,23 @@ If you prefer to change the port manually: OAUTH2_ISSUER=http://localhost:8080 # Update to match new port ``` -2. **Edit the systemd service file**: +2. **Restart the service**: ```bash - sudo nano /etc/systemd/system/mockapi.service - ``` - Update the `ExecStart` line: - ```ini - ExecStart=/opt/mockapi/venv/bin/waitress-serve --host=0.0.0.0 --port=8080 wsgi:wsgi_app - ``` - -3. **Reload systemd and restart**: - ```bash - sudo systemctl daemon-reload sudo systemctl restart mockapi - sudo systemctl status mockapi ``` -4. **Verify the change**: +3. **Verify the change**: ```bash curl http://localhost:8080/health ``` **Important Notes**: -- The port in `.env` and service file must match +- The systemd service automatically reads HOST and PORT from `.env` file at runtime +- No need to edit the service file when changing ports - After changing port, update any reverse proxy configurations - OAuth2 clients may need reconfiguration if issuer URL changes -**Checking Current Configuration**: -To verify your port configuration is consistent, use the check script: -```bash -cd /opt/mockapi -sudo wget -O check_port_config.sh https://raw.githubusercontent.com/your-repo/main/check_port_config.sh -sudo chmod +x check_port_config.sh -sudo bash check_port_config.sh -``` - -The script will: -- Show current port settings from `.env` and service file -- Check for consistency between files -- Verify service is running and listening on correct port -- Test health endpoint -- Provide recommendations if issues are found - -### 4. **Reverse Proxy (Recommended)** +### 5. **Reverse Proxy (Recommended)** Use Nginx or Apache as a reverse proxy for SSL termination, load balancing, and static file serving: **Example Nginx configuration**: @@ -378,7 +367,7 @@ server { } ``` -### 4. **Database Backups** +### 6. **Database Backups** For SQLite, regularly backup the `mockapi.db` file. For production, consider migrating to PostgreSQL. ## Usage @@ -581,7 +570,7 @@ Enable debug logging by setting `DEBUG=True` in `.env`. Check the console output - SQLite only (but can be extended to PostgreSQL via `DATABASE_URL`) - Single admin user (no multi‑user support) - No request logging/history - - OAuth2 protection fields (requires_oauth, oauth_scopes) not exposed in admin UI + - OAuth2 protection fields (requires_oauth, oauth_scopes) for endpoints not exposed in admin UI (though OAuth client/token/user management is available via navigation dropdown) - OAuth2 user authentication uses placeholder user IDs (integration with external identity providers pending) - **Possible extensions**: diff --git a/app/modules/admin/templates/base.html b/app/modules/admin/templates/base.html index 2654048..e05d372 100644 --- a/app/modules/admin/templates/base.html +++ b/app/modules/admin/templates/base.html @@ -39,6 +39,16 @@ Endpoints +
  • + + +