diff --git a/.github/workflows/image_build.yaml b/.github/workflows/image_build.yaml
new file mode 100644
index 0000000..b392393
--- /dev/null
+++ b/.github/workflows/image_build.yaml
@@ -0,0 +1,38 @@
+name: Build and release Docker image
+
+on:
+  release:
+    types: [published]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    # perms for token
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: checkout repo
+        uses: actions/checkout@v4.1.1
+      - name: container registry auth
+        uses: docker/login-action@v3.1.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: generate tags, label
+        id: meta
+        uses: docker/metadata-action@v5.5.1
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+      - name: image build and push
+        uses: docker/build-push-action@v5.3.0
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f0dd0a6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,20 @@
+# portfolio-site
+Website to highlight personal projects, written in Python, built on Flask and Jinja templating.
+
+## YAML-based posts
+
+Individual project posts to the home page are defined via yaml files, with support for proper HTML tags (headings and subheadings, paragraph text, divs, and more) in addition to inline code snippets and images.
+
+I chose this approach as an introduction to working with Flask and to leverage Jinja templates in a way I haven't seen before. This project design allows to me to maintain the site without needing a more complex solution for blog post entries, such as a database.
+
+## Docker
+### Image
+A docker image that runs this application is available under the repo packages, or at `ghcr.io/holysoles/portfolio-site`.
+### Compose
+An example compose file can be found in the repo [here](https://github.com/holysoles/portfolio-site/blob/master/compose.yaml)
+### Building
+`docker build --tag ghcr.io/holysoles/portfolio-site:<tag> .`
+### Testing
+`docker run --rm -d -p 5000:5000 ghcr.io/holysoles/portfolio-site:<tag>`
+### Upload
+`docker push ghcr.io/holysoles/portfolio-site:<tag>`
\ No newline at end of file
diff --git a/compose.yaml b/compose.yaml
new file mode 100644
index 0000000..0a7e038
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,11 @@
+version: '3.9'
+services:
+  site:
+    image: ghcr.io/holysoles/portfolio-site:latest
+    ports:
+      - "5000:5000/tcp"
+    deploy:
+      mode: replicated 
+      replicas: 2
+      update_config:
+        delay: 30s