Merge pull request #74 from Imageomics/docs/deployment

Update deployment documentation

.github/workflows/deploy-image.yml

@@ -0,0 +1,52 @@
+name: Create and publish a Docker image
+# Reference: https://docs.github.com/en/actions/publishing-packages/publishing-docker-images#publishing-images-to-github-packages
+
+# Configures this workflow to run every time a release is published.
+on:
+  release:
+    types: [published]
+
+# Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+# There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: write
+      # 
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{major}}.{{minor}}.{{patch}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}      
+      # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
+      # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
+      # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

Dockerfile

@@ -0,0 +1,23 @@
+FROM node:18.16.0 as builder
+WORKDIR /src
+COPY ./andromeda-ui/package.json ./
+RUN npm install
+COPY ./andromeda-ui/. .
+RUN npm run build
+
+FROM python:3.11
+
+COPY ./andromeda/requirements.txt /tmp/requirements.txt
+WORKDIR /tmp
+RUN pip3 install gunicorn && pip3 install -r requirements.txt
+
+COPY ./andromeda/. /api
+COPY --from=builder /src/out /api/static
+WORKDIR /api
+
+# fix since root home directory is read only in HF
+RUN mkdir /tmp/home
+RUN chmod a+w /tmp/home
+ENV XDG_DATA_HOME=/tmp/home
+
+CMD /api/run.sh

README.md

@@ -2,62 +2,25 @@
 Andromeda is a website that allows a user to perform dimensional reduction on an uploaded CSV file.
 
 ## Requirements
-Deployment requires [docker-compose](https://www.docker.com/).
+Deployment requires [Docker](https://www.docker.com/).
 
 Development requires [python3](https://www.python.org/) and [nodejs](https://nodejs.org/).
 
 ## Deployment
-To deploy the website on a machine running docker run the following commands:
-```bash
-git clone https://github.com/Imageomics/Andromeda.git
-cd Andromeda/
-cp example.env .env
-docker-compose up -d
-```
-The `-d` flag runs the website in the background. For troubleshooting remove this flag to more easily monitor the deployment.
-
-Once the website finishes launching the website will be available on port 80: [http://localhost](http://localhost).
-Part of the deployment builds the docker containers used by the website, so it may take a few minutes to finish deployment.
-To stop the app run `docker-compose down`.
-
-Settings for the app can be changed in `.env`.
-Options for `.env`:
-- BACKEND_WORKERS - number of [workers used by gunicorn](https://docs.gunicorn.org/en/latest/run.html#commonly-used-arguments)
-- ANDROMEDA_RGB_SATELLITE_URL - URL pointing to a CSV file for joining RGB data
-
-### Certbot Setup on AWS
-Certificates can be installed to the EC2 VM using Certbot with Nginx on pip following [EFF instructions](https://certbot.eff.org/instructions?ws=nginx&os=pip).
-```bash
-sudo python3 -m venv /opt/certbot/
-sudo /opt/certbot/bin/pip install --upgrade pip
-sudo /opt/certbot/bin/pip install certbot certbot-nginx
-sudo ln -s /opt/certbot/bin/certbot /usr/bin/certbot
-```
-And to install Nginx on the Amazon Linux 2023 (following [instructions](https://awswithatiq.com/how-to-install-nginx-in-amazon-linux-2023/)) and run Certbot:
-```bash
-docker-compose down
-sudo dnf update -y
-sudo dnf install nginx -y
-sudo systemctl start nginx
-sudo certbot certonly --nginx
-```
-Following prompted agreements, registration, and specifying andromeda.imageomics.org, the certificates are installed to:
-
-Certificate: `/etc/letsencrypt/live/andromeda.imageomics.org/fullchain.pem`
-
-Key: `/etc/letsencrypt/live/andromeda.imageomics.org/privkey.pem`
-
-Finally, shut down Nginx on the system to avoid interference with the container:
-```bash
-sudo systemctl stop nginx
-docker-compose up -d
-```
+Our primary deployment environment is [Hugging Face Spaces](https://huggingface.co/spaces/imageomics/Andromeda).
+To deploy a new version change the version in the tag in the [Andromeda Space Dockerfile](https://huggingface.co/spaces/imageomics/Andromeda/blob/main/Dockerfile).
+Hugging Face handles SSL encryption automatically. 
+Deploying in another environment may require additional configuration; previous configurations are discussed in [Prior Configurations](https://github.com/Imageomics/Andromeda/wiki/Prior-Configurations).
 
 ## Development
-To run the website locally without using docker requires two terminal sessions.
+You may use the Docker image for testing during development as described above, but it is not required.
+
+To run the website locally without using Docker requires two terminal sessions.
 1. Python Flask Backend API Server 
 2. Frontend nodejs/react development server
 
+For instructions on buliding and running the Docker container see [Developing with Docker](https://github.com/Imageomics/Andromeda/wiki/Developing-with-Docker).
+
 ## Python Backend
 The python backend consists of a [Flask](https://flask.palletsprojects.com/en/2.3.x/quickstart/#a-minimal-application) REST API server.
 See the [Andromeda Python README](andromeda/README.md) for instructions on running locally.

andromeda/app.py

@@ -0,0 +1,13 @@
+# Adds logic to serve static html for running within huggingface
+from flask import send_from_directory, request
+from main import app
+
+@app.errorhandler(404)
+def page_not_found(e):
+    path = request.path.lstrip('/')
+    if path == '':
+       path = 'index.html'
+    return send_from_directory('static', path)
+
+if __name__ == '__main__':
+   app.run(host="0.0.0.0", port=7860)

andromeda/run.sh

@@ -1,2 +1,2 @@
 #!/bin/bash
-gunicorn -w ${BACKEND_WORKERS:=4} -b :5000 -t 360 wsgi:app
+gunicorn -w ${BACKEND_WORKERS:=4} -b :7860 -t 360 wsgi:app

andromeda/wsgi.py

@@ -1,4 +1,4 @@
-from main import app
+from app import app
 
 if __name__ == "__main__":
     app.run()