docker cleanup and setup improvements

Joshua Fishman · Joshua Fishman · commit 39e26d2ed3fe · 2025-09-15T11:11:09.000-07:00
- Remove obsolete version attribute from docker-compose.yml
- Simplify Docker setup to use docker compose up command
- Update README with Docker-first approach and clear instructions
- Update CONTRIBUTING.md with proper Docker commands and workflow
- Enhance package.json with better development scripts
- Improve entrypoint.sh with initial Sass build and clear logging
- Add comprehensive documentation for live reload functionality
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -11,11 +11,10 @@
    - [**Prerequisites**](#prerequisites)
    - [**Setup Instructions**](#setup-instructions)
       - [1. Fork and Clone this repository](#1-fork-and-clone-this-repository)
-      - [2. Install Dependencies](#2-install-dependencies)
-      - [3. Docker Setup](#3-docker-setup)
-      - [4. Starting Docker](#4-starting-docker)
-      - [5. Stopping Docker](#5-stopping-docker)
-      - [Docker Notes](#docker-notes)
+      - [2. Starting the Development Environment](#2-starting-the-development-environment)
+      - [3. Stopping Docker](#3-stopping-docker)
+      - [4. Development Workflow](#4-development-workflow)
+      - [Docker Development Notes](#docker-development-notes)
 - [**Working on issues**](#working-on-issues)
    - [**Branch Workflow**](#branch-workflow)
 - [**Create an issue**](#create-an-issue)
@@ -67,33 +66,74 @@
    upstream        https://github.com/hackforla/internship-website-design-system.git (push)
    ```
 
-#### 1. **Docker Setup**
-- #### **Enter repo directory:**
+#### 2. **Starting the Development Environment**
+
+**IMPORTANT:** Make sure **Docker Desktop** is running on your computer before executing the commands below.
+
+- #### **Navigate to the project directory:**
    ```bash 
    cd internship-website-design-system
    ```
-- #### **Build the Docker image:** 
-   ```bash 
-   docker build -t ds .
+
+- #### **Start the development environment:**
+   ```bash
+   docker compose up
    ```
-   This command builds a Docker image named `ds` from the Dockerfile in the current directory.
-   Note: If you have a permissions error run `sudo docker build -t ds .` and enter your machine's admin password.
+   This command will:
+   - Build the Docker image automatically
+   - Install all npm dependencies
+   - Compile Sass files initially
+   - Start the Sass watcher for live CSS compilation
+   - Start MkDocs server with live reload
+   - Set up file watching for automatic updates
+
+- #### **View the site:**
+   Open your browser and navigate to: **http://localhost:8000**
    
-#### 2. **Starting Docker**
-**IMPORTANT:** Please make sure the `Docker Desktop` application is **running on your computer** before you run the bash commands below.
-- #### Run the Docker container.
+   Both Sass changes and documentation changes will automatically reload in your browser.
+
+- #### **Alternative Docker Commands:**
    ```bash
-   docker run -p 8000:8000 -v $(pwd):/docs ds
+   # Start in background (detached mode)
+   docker compose up -d
+   
+   # Build fresh and start
+   docker compose up --build
+   
+   # View logs while running in background
+   docker compose logs -f
+   
+   # Check container status
+   docker compose ps
    ```
-   This command runs the `ds` image as a container and maps the container's port 8000 to port 8000 on your host machine, allowing you to access the          MkDocs server. View the site by navigating to `[http://localhost:8000](http://0.0.0.0:8000/internship-website-design-system/)` in your web browser. You should see your MkDocs site being served from the Docker           container.
    
-#### 5. **Stopping Docker**
-Simply press `CTRL + C` in the terminal where the container is running. This sends a SIGINT signal, initiating a graceful shutdown of the container. If it doesn't stop, pressing `CTRL + C` again forces a more abrupt termination.
+#### 3. **Stopping Docker**
+- **If running in foreground:** Press `Ctrl + C` in the terminal
+- **If running in background:** Run `docker compose down`
    
-#### Docker Notes:
+#### 4. **Development Workflow**
+
+1. **Edit Sass files** in `docs/components/sass/`
+2. **Changes auto-compile** and browser refreshes automatically
+3. **Edit documentation** in `docs/*.md` files  
+4. **Changes auto-reload** in the browser
+
+#### Docker Development Notes:
 
-- Changes to any files will automatically be displayed in your browser if the Docker image is ran with `docker run -p 8000:8000 -v $(pwd):/docs ds` as previously mentioned.
-- If the default port (8000) is already in use on your machine, you can map the container's port to a different port on your host machine by changing the first   `8000` in the `docker run` command to a free port, e.g., `docker run -p 8001:8000 ds`.
+- **Live reload works for both CSS and documentation** - no manual refresh needed
+- **File changes are instant** - the container watches your local files
+- **Port 8000** serves the MkDocs site, **port 35729** handles live reload
+- **If port 8000 is busy:** Stop other services using that port or change the port mapping in `docker-compose.yml`
+- **Container commands:** If you need to run commands inside the container:
+  ```bash
+  # Access container shell
+  docker compose exec mkdocs sh
+  
+  # Inside container you can run:
+  npm run dev          # Start only Sass watcher
+  npm run build-sass   # Build Sass once
+  npm run clean        # Clean compiled CSS
+  ```
 
 ## Working on issues
 
@@ -145,7 +185,7 @@ After pushing your branch to your fork, navigate to the [original repository](ht
 ## Testing
 <!-- Talk about Accessibility Testing -->
 
-- Run and view the site locally. See [Starting Docker](#3-starting-docker)
+- Run and view the site locally. See [Starting the Development Environment](#2-starting-the-development-environment)
 - Observe visual changes for desktop-sized screens as well as mobile.
   
 ### Automated Accessibility Testing
diff --git a/README.md b/README.md
@@ -2,40 +2,128 @@
 
 This design system is a project of _Hack for LA_. It helps teams customize and develop their websites and applications. This design system is meant to provide necessary web components and make them easy to customize.
 
-It runs on Docker like so: 
+## 🚀 Quick Start
+
+### Start Development (Docker)
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/hackforla/internship-website-design-system.git
+   cd internship-website-design-system
+   ```
+
+2. **Start the development environment:**
+   ```bash
+   docker-compose up
+   ```
+   This automatically:
+   - Installs all dependencies
+   - Compiles Sass files
+   - Starts Sass watcher for live CSS compilation
+   - Starts MkDocs server with live reload
+   - Sets up file watching for changes
+
+3. **Open your browser:**
+   - Visit: http://localhost:8000
+   - Both Sass changes and documentation changes will auto-reload
+
+4. **Stop development:**
+   ```bash
+   # Press Ctrl+C in the terminal, or:
+   docker-compose down
+   ```
+
+### Alternative Docker Commands
+
 ```bash
-docker run -p 8000:8000 -v ${PWD}:/app mkdocs-site
+# Build and start fresh
+docker-compose up --build
+
+# Run in background
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop background process
+docker-compose down
 ```
 
-### Wiki
+## 🛠️ Development Workflow
 
-For more information on contributing
-[Software Engineer Wiki](https://github.com/hackforla/internship/wiki/Software-Engineer)
+1. **Edit Sass files** in `docs/components/sass/`
+2. **Changes auto-compile** and browser auto-refreshes
+3. **Edit documentation** in `docs/*.md` files  
+4. **Changes auto-reload** in browser
+
+### Internal Commands (Run Inside Container)
+
+If you need to run commands inside the container:
+
+```bash
+# Access container shell
+docker-compose exec mkdocs sh
+
+# Inside container, you can run:
+npm run dev          # Start only Sass watcher
+npm run build-sass   # Build Sass once
+npm run clean        # Clean compiled CSS
+npm run build        # Build for production
+```
+
+## 📁 Project Structure
+
+```
+docs/
+├── components/sass/          # Source Sass files
+│   ├── main.scss            # Main entry point
+│   ├── abstracts/           # Variables, mixins
+│   ├── components/          # Button, form components
+│   └── layout/              # Grid, tabs
+├── dist/                    # Compiled CSS (auto-generated)
+│   └── main.css            # Output CSS file
+└── *.md                     # Documentation pages
+```
+
+## 🎨 Working with Styles
+
+1. **Edit Sass files** in `docs/components/sass/`
+2. **Changes auto-compile** when Docker is running
+3. **Browser auto-refreshes** to show your changes
+4. **Compiled CSS** appears in `docs/dist/main.css`
+
+## 🐳 Docker Setup Details
+
+The Docker setup includes:
+- **Node.js & npm** for Sass compilation
+- **Python & pip** for MkDocs
+- **Live reload** for both CSS and documentation
+- **Volume mounting** for instant file changes
+- **Port forwarding** (8000 for site, 35729 for live reload)
 
 ### Technology used
 
-- [GitHub Pages](https://pages.github.com/)
-- [Jekyll](https://jekyllrb.com/docs/)
-- [MK Docs](https://www.mkdocs.org/)
-- [Material for MK Docs](https://squidfunk.github.io/mkdocs-material/)
+- [MK Docs](https://www.mkdocs.org/) with [Material theme](https://squidfunk.github.io/mkdocs-material/)
 - [SASS](https://sass-lang.com/)
-- [Docker](https://docker.com)
+- [Docker](https://docker.com) & Docker Compose
+- [GitHub Pages](https://pages.github.com/) for deployment
 
-<!-- Explain the different ways people can contribute. For example: -->
+## 🤝 Contributing
 
+- [How to Contribute](CONTRIBUTING.md)
 - This is a project of _Hack for LA_, please [join here](https://www.hackforla.org/join)
-- Join the team on Slack on [#internship](https://hackforla.slack.com/archives/C01VAUPU788)
-
-# Contributing
+- Join the team on Slack: [#internship](https://hackforla.slack.com/archives/C01VAUPU788)
 
-- [How to Contribute](CONTRIBUTING.md)
+## 🔗 Links
 
-# Contact info
+### Wiki
+[Software Engineer Wiki](https://github.com/hackforla/internship/wiki/Software-Engineer)
 
-- Message the team on Slack: [#internship](https://hackforla.slack.com/archives/C01VAUPU788)
+### Contact info
+Message the team on Slack: [#internship](https://hackforla.slack.com/archives/C01VAUPU788)
 
 ### Licensing
-
 [GPL-2.0 license](https://github.com/hackforla/internship-website-design-system#GPL-2.0-1-ov-file)
 
+---
 _this readme file sourced from [Jessica Sand](http://jessicasand.com/other-stuff/just-enough-docs/)_
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,4 +1,3 @@
-version: '3.9'
 services:
   mkdocs:
     build: .
@@ -10,7 +9,5 @@ services:
       - "35729:35729"
     stdin_open: true
     tty: true
-command: mkdocs serve --dev-addr=0.0.0.0:8000
-watch:
-  - action: rebuild
-    path: package.json
+    # Override the default command to ensure both Sass and MkDocs run
+    command: sh -c "npm run dev & mkdocs serve --dev-addr=0.0.0.0:8000 --livereload"
diff --git a/entrypoint.sh b/entrypoint.sh
@@ -1,4 +1,13 @@
 #!/bin/sh
 
+# Ensure Sass is compiled initially
+echo "Building Sass files..."
+npm run build-sass
+
+# Start Sass watcher in background
+echo "Starting Sass watcher..."
 npm run dev &
-mkdocs serve --dev-addr=0.0.0.0:8000
+
+# Start MkDocs with live reload
+echo "Starting MkDocs server with live reload..."
+mkdocs serve --dev-addr=0.0.0.0:8000 --livereload
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
