Update CI/CD

Author: ljfp

.github/workflows/deploy.yml

@@ -32,21 +32,28 @@ jobs:
           REMOTE_APP_DIR: ${{ env.APP_DIR }}
         run: |
           set -euo pipefail
-          APP_DIR="${REMOTE_APP_DIR:-/home/ubuntu/nasa-sky-explorer}"
-          ssh "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}" "mkdir -p ${APP_DIR}"
+          APP_DIR="${REMOTE_APP_DIR:-/opt/nasa-sky-explorer}"
+          ssh "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}" "sudo mkdir -p ${APP_DIR}"
 
       - name: Sync repository to EC2
         env:
           REMOTE_APP_DIR: ${{ env.APP_DIR }}
         run: |
           set -euo pipefail
-          APP_DIR="${REMOTE_APP_DIR:-/home/ubuntu/nasa-sky-explorer}"
+          APP_DIR="${REMOTE_APP_DIR:-/opt/nasa-sky-explorer}"
+          TEMP_DIR="/tmp/nasa-sky-explorer-deploy-$$"
+          
+          # Sync to temp directory first
+          ssh "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}" "mkdir -p ${TEMP_DIR}"
           rsync -az --delete \
             --exclude ".git" \
             --exclude ".github/" \
             --exclude ".venv/" \
             --exclude "logs/" \
-            ./ "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}:${APP_DIR}/"
+            ./ "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}:${TEMP_DIR}/"
+          
+          # Move from temp to final location with sudo
+          ssh "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}" "sudo rsync -a --delete ${TEMP_DIR}/ ${APP_DIR}/ && rm -rf ${TEMP_DIR}"
 
       - name: Install Python dependencies and restart the service
         env:
@@ -56,10 +63,10 @@ jobs:
           REMOTE_PORT: ${{ env.UVICORN_PORT }}
         run: |
           set -euo pipefail
-          APP_DIR="${REMOTE_APP_DIR:-/home/ubuntu/nasa-sky-explorer}"
+          APP_DIR="${REMOTE_APP_DIR:-/opt/nasa-sky-explorer}"
           PYTHON_BIN="${REMOTE_PYTHON_BIN:-/usr/bin/python3}"
           SERVICE_NAME="${REMOTE_SERVICE:-nasaspaceapps}"
-          UVICORN_PORT="${REMOTE_PORT:-8000}"
+          UVICORN_PORT="${REMOTE_PORT:-80}"
 
           ssh "${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}" \
-            "cd '${APP_DIR}' && APP_DIR='${APP_DIR}' PYTHON_BIN='${PYTHON_BIN}' SERVICE_NAME='${SERVICE_NAME}' UVICORN_PORT='${UVICORN_PORT}' bash deploy/remote_deploy.sh"
+            "cd '${APP_DIR}' && sudo APP_DIR='${APP_DIR}' PYTHON_BIN='${PYTHON_BIN}' SERVICE_NAME='${SERVICE_NAME}' UVICORN_PORT='${UVICORN_PORT}' bash deploy/remote_deploy.sh"

README.md

@@ -42,18 +42,24 @@ ruff check .
 
 ```
 NASASpaceAppsChallenge2025/
-├── requirements.txt      # FastAPI and Uvicorn dependencies
+├── requirements.txt                    # FastAPI and Uvicorn dependencies
 ├── src/
 │   ├── __init__.py
-│   └── server.py         # FastAPI application serving the HTML page
+│   └── server.py                       # FastAPI application serving the HTML page
 ├── web/
-│   ├── index.html        # Landing page served at the root route
-│   └── aladin.html       # Secondary page under /aladin
+│   ├── index.html                      # Landing page served at the root route
+│   ├── aladin.html                     # FITS explorer with Aladin Lite integration
+│   └── styles.css                      # Styling for the viewer interface
 ├── deploy/
-│   └── remote_deploy.sh  # Remote helper script invoked by the CI workflow
-└── .github/
-    └── workflows/
-        └── deploy.yml    # Continuous deployment pipeline for EC2
+│   ├── remote_deploy.sh                # Remote deployment script (run on EC2)
+│   └── nasaspaceapps.service.template  # SystemD service unit template
+├── .github/
+│   └── workflows/
+│       └── deploy.yml                  # Continuous deployment pipeline for EC2
+├── README.md                           # Main documentation
+├── MIGRATION.md                        # Migration guide for existing deployments
+├── DEPLOYMENT_CHANGES.md               # Detailed deployment architecture documentation
+└── OPS_REFERENCE.md                    # Quick reference for operations team
 ```
 
 Feel free to extend the UI with annotations, multi-layer comparisons, or temporal sliders to address the broader Space Apps challenge goals.
@@ -64,33 +70,46 @@ Every push to `main` triggers the GitHub Actions workflow in `.github/workflows/
 pipeline performs the following steps:
 
 1. Checks out the latest code.
-2. Copies the repository to your EC2 instance via `rsync` (preserving any existing `.venv` or
-   `logs` folders).
-3. Runs `deploy/remote_deploy.sh` on the instance to create/refresh a virtual environment, install
-   dependencies, and restart the application via `systemd` when available. If a systemd service is
-   not present, it falls back to launching Uvicorn in the background with `nohup`.
+2. Copies the repository to `/opt/nasa-sky-explorer` on your EC2 instance via `rsync`.
+3. Creates a dedicated service user (`nasaapp`) if it doesn't exist.
+4. Sets proper ownership and permissions for the application directory.
+5. Installs Python dependencies in a virtual environment owned by the service user.
+6. Applies necessary capabilities to bind to port 80 (if running on a privileged port).
+7. Restarts the systemd service or launches Uvicorn as a background process.
 
 ### Required GitHub secrets
 
 Create the following secrets at **Settings → Secrets and variables → Actions**:
 
 - `EC2_HOST` – Public DNS name or IP address of the instance.
-- `EC2_USER` – SSH user (for example, `ubuntu`).
+- `EC2_USER` – SSH user with sudo privileges (for example, `ubuntu`).
 - `EC2_SSH_KEY` – Private SSH key allowed to log in as `EC2_USER`.
 
 ### Optional overrides
 
 You can customise the deployment without editing the workflow by providing additional (optional)
 secrets:
 
-- `EC2_APP_DIR` – Absolute path where the repo should live (defaults to `/home/ubuntu/nasa-sky-explorer`).
+- `EC2_APP_DIR` – Absolute path where the repo should live (defaults to `/opt/nasa-sky-explorer`).
 - `EC2_PYTHON_BIN` – Python interpreter used to build the virtual environment (defaults to
   `/usr/bin/python3`).
 - `EC2_SERVICE_NAME` – Name of the `systemd` service to restart (defaults to `nasaspaceapps`).
-- `EC2_UVICORN_PORT` – Port exposed by Uvicorn when no `systemd` unit is available (defaults to
-  `8000`).
+- `EC2_UVICORN_PORT` – Port exposed by Uvicorn (defaults to `80`).
 
-Ensure the EC2 machine has `git`, `rsync`, `python3`, and `pip` installed. If you prefer a managed
-service, create a `systemd` unit named after `EC2_SERVICE_NAME` that executes
-`/home/ubuntu/nasa-sky-explorer/.venv/bin/uvicorn src.server:app --host 0.0.0.0 --port 8000`
-and the workflow will restart it after each deployment.
+### Setting up the systemd service
+
+For production use, create a systemd service to manage the application lifecycle:
+
+```bash
+# On your EC2 instance:
+sudo cp /opt/nasa-sky-explorer/deploy/nasaspaceapps.service.template /etc/systemd/system/nasaspaceapps.service
+sudo systemctl daemon-reload
+sudo systemctl enable nasaspaceapps.service
+sudo systemctl start nasaspaceapps.service
+```
+
+The service runs as the `nasaapp` user and automatically restarts on failure. Logs are written to
+`/opt/nasa-sky-explorer/logs/uvicorn.log`.
+
+**Note:** The application directory `/opt/nasa-sky-explorer` is accessible to all sudo users, and the
+service runs under a dedicated unprivileged user (`nasaapp`) for security.

deploy/nasaspaceapps.service.template

@@ -0,0 +1,27 @@
+[Unit]
+Description=NASA Sky Explorer Web Application
+After=network.target
+
+[Service]
+Type=simple
+User=nasaapp
+Group=nasaapp
+WorkingDirectory=/opt/nasa-sky-explorer
+Environment="PATH=/opt/nasa-sky-explorer/.venv/bin:/usr/local/bin:/usr/bin:/bin"
+ExecStart=/opt/nasa-sky-explorer/.venv/bin/uvicorn src.server:app --host 0.0.0.0 --port 80
+Restart=always
+RestartSec=10
+
+# Security hardening
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/nasa-sky-explorer/logs
+
+# Logging
+StandardOutput=append:/opt/nasa-sky-explorer/logs/uvicorn.log
+StandardError=append:/opt/nasa-sky-explorer/logs/uvicorn.log
+
+[Install]
+WantedBy=multi-user.target

deploy/remote_deploy.sh

@@ -4,32 +4,57 @@ set -euo pipefail
 APP_DIR="${APP_DIR:-$(pwd)}"
 PYTHON_BIN="${PYTHON_BIN:-/usr/bin/python3}"
 SERVICE_NAME="${SERVICE_NAME:-nasaspaceapps}"
-UVICORN_PORT="${UVICORN_PORT:-8000}"
+UVICORN_PORT="${UVICORN_PORT:-80}"
+APP_USER="${APP_USER:-nasaapp}"
 
+# Create dedicated service user if it doesn't exist
+if ! id "${APP_USER}" >/dev/null 2>&1; then
+  echo "Creating service user ${APP_USER}..."
+  useradd --system --no-create-home --shell /usr/sbin/nologin "${APP_USER}"
+fi
+
+# Set ownership and permissions for app directory
+chown -R "${APP_USER}:${APP_USER}" "${APP_DIR}"
+chmod -R 755 "${APP_DIR}"
+
+# Create and setup virtual environment as the service user
 if [ ! -d ".venv" ]; then
-  "${PYTHON_BIN}" -m venv .venv
+  sudo -u "${APP_USER}" "${PYTHON_BIN}" -m venv .venv
 fi
 
+# Install dependencies as the service user
 # shellcheck source=/dev/null
+sudo -u "${APP_USER}" bash << 'EOSCRIPT'
 source .venv/bin/activate
 pip install --upgrade pip wheel
 pip install -r requirements.txt
-
 deactivate || true
+EOSCRIPT
+
+# Apply capability to allow binding to port 80 (if port < 1024)
+if [ "${UVICORN_PORT}" -lt 1024 ]; then
+  REAL_PYTHON=$(readlink -f "${APP_DIR}/.venv/bin/python")
+  if [ -f "${REAL_PYTHON}" ]; then
+    echo "Applying cap_net_bind_service to ${REAL_PYTHON}..."
+    setcap 'cap_net_bind_service=+ep' "${REAL_PYTHON}" || echo "Warning: Failed to set capability"
+  fi
+fi
 
 LOG_DIR="${APP_DIR}/logs"
 mkdir -p "${LOG_DIR}"
+chown "${APP_USER}:${APP_USER}" "${LOG_DIR}"
+chmod 755 "${LOG_DIR}"
 
 if command -v systemctl >/dev/null 2>&1; then
-  sudo systemctl daemon-reload || true
-  if sudo systemctl list-unit-files | grep -q "^${SERVICE_NAME}\.service"; then
-    sudo systemctl restart "${SERVICE_NAME}.service"
+  systemctl daemon-reload || true
+  if systemctl list-unit-files | grep -q "^${SERVICE_NAME}\.service"; then
+    systemctl restart "${SERVICE_NAME}.service"
     exit 0
   fi
 fi
 
 echo "systemd unit ${SERVICE_NAME}.service not found or unavailable. Relaunching Uvicorn with nohup."
 
 pkill -f "uvicorn src.server:app" || true
-nohup "${APP_DIR}/.venv/bin/uvicorn" src.server:app --host 0.0.0.0 --port "${UVICORN_PORT}" \
+sudo -u "${APP_USER}" nohup "${APP_DIR}/.venv/bin/uvicorn" src.server:app --host 0.0.0.0 --port "${UVICORN_PORT}" \
   >"${LOG_DIR}/uvicorn.log" 2>&1 &