MDServe

A minimalistic web server that converts pages written in Markdown to HTML. It will serve any Markdown located in the pages directory as HTML using the file's path as its access point. Files named index.md are considered base routes. For instance:

• The file pages/index.md is accessible at /
• The file pages/blog/ireland.md is accessible at /blog/ireland
• The file pages/blog/index.md is accessible at /blog

The site's layout is defined by the HTML in public/index.html. Opening that file, you'll notice the token %APP% which is where a page's converted HTML gets injected.

Browser Javascript

MDServe does not enable client-side Javascript by default. If your application requires it, you have a couple options:

• If plain Javascript is all you need, add it to the public directory and add referenced <script> tag(s) to public/index.html.
• If you prefer Typescript, files in the src/js/ directory are served by a special /js* handler. Open public/index.html and uncomment the script tag referencing /js/main.js. This js/main.js file is emitted by the Typescript compiler from src/js/main.ts. You may add additional Typescript to src/js/ but, since it is executed in the browser, it needs to be bundled in order to use require/import statements.

Project structure

• pages/ - Stores Markdown pages and defines the site's routing
• public/ - Static assets
• src/ - The ExpressJS server

Requirements

• NodeJS v18 or higher
• Optional: Docker

Getting started

1. Clone this repository

   git clone https://github.com/dan-lovelace/md-serve.git

2. Change into the new directory

   cd md-serve

3. Start the server using one of the following options: from source or with Docker

Running from source

1. Install dependencies

   npm install

2. Start the development server

   npm run dev

Running with Docker

• Build and run the container using default configuration

  docker compose up --build

• Build and run using a specific environment file

  docker compose --env-file=".env.development" up --build

Local development

The npm run dev command starts the server from source and watches for changes to the pages, public and src directories. The base HTML inherited by all pages can be found in public/index.html and anything in the public directory is served statically.

There is a src/js directory that is used to store any necessary Javascript for the browser. There is no bundling solution shipped by default but one could be added depending on needs.

Docker and AWS

Building and pushing an image to ECR

1. Create a new repository in ECR

   aws ecr create-repository md-serve

2. Login to the new repository with Docker - Replace ACCOUNT_NUMBER and REGION with your own

   aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ACCOUNT_NUMBER.dkr.ecr.REGION.amazonaws.com/md-serve

3. Build the latest image

   docker compose build

   • Note: You may provide an environment file using the --env-file flag like this: docker compose --env-file=".env.production" build
4. Create a tag pointing to the ECR repository - Replace ACCOUNT_NUMBER and REGION with your own

   docker tag md-web-server:latest ACCOUNT_NUMBER.dkr.ecr.REGION.amazonaws.com/md-serve

5. Push the image to the remote repository

   docker push ACCOUNT_NUMBER.dkr.ecr.REGION.amazonaws.com/md-serve

Deployment

Below are some very loose steps for AWS deployment options and there is an endless list of other options for hosting Docker containers.

EC2

1. Create a new EC2 instance using an image that has Linux and Docker - Look in the AWS marketplace
2. Create an elastic IP and associate it with the instance
3. SSH into the machine and run that aws ecr get-login-password ... | docker login ... command from above to login to docker - Run aws configure to set up credentials or edit ~/.aws/config and ~/.aws/credentials manually
4. Pull the image docker pull ACCOUNT_NUMBER.dkr.ecr.REGION.amazonaws.com/md-serve-repo:latest
5. Get the image id with docker images
6. Run it using the image id and expose the correct port(s) docker run -d -p 8000:8000 2ce25025a251
7. Navigate to the instance's public IP
8. Homepage should display

ECS

1. Create a new ECS cluster
2. Create a new ECS Task Definition using the ECR image
3. Create a new ECS Service that uses the new Task Definition
4. Wait for task to start and select it
5. Navigate to the task's public IP
6. Homepage should display

Assign static IP to ECS service

https://repost.aws/knowledge-center/ecs-fargate-static-elastic-ip-address