Merge pull request #170 from DefangLabs/starter-sample

Starter sample

Author: raphaeltm

README.md

@@ -3,3 +3,7 @@
 Samples to show you how to develop, deploy, and debug cloud applications with Defang.
 
 Browse through the [./samples](./samples) directory, or search and browse in the [docs](https://docs.defang.io/docs/samples).
+
+## Adding Samples
+
+To start working on a new sample, run `. ./scripts/new-sample.sh` from the root of the repository. This will create a new sample directory, with some basic scaffolding to get you started. Look for `#REMOVE_ME_AFTER_EDITING` in your new project to look for things that you should probably be changing/checking per sample. Feel free to remove files, like `compose.dev.yaml` if they aren't necessary for your sample.

scripts/check-sample-files.sh

@@ -22,4 +22,13 @@ for dir in ./samples/*/; do
       echo " - [ ] add 'Languages:' to README.md in ${dir}"
     fi
   fi
+
+  # Check for #REMOVE_ME_AFTER_EDITING
+  matches=$(grep -rnH "#REMOVE_ME_AFTER_EDITING" $dir* | cut -d: -f1,2)
+
+  if [ -n "$matches" ]; then
+    echo "$matches" | while read -r line; do
+      echo " - [ ] $line contains #REMOVE_ME_AFTER_EDITING... did you forget to edit this section?"
+    done
+  fi
 done

scripts/new-sample.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+while true; do
+  # prompt for a directory name for the sample (should be kebab-case)
+  printf "Enter the name of the sample (kebab-case): "
+  read -r sample_name
+
+  # make sure it's actually kebab-case
+  if [[ ! "$sample_name" =~ ^[a-z0-9-]+$ ]]; then
+    echo "Sample name must be kebab-case"
+    continue
+  fi
+
+  # check if dir exists in the samples directory
+  if [ -d "samples/$sample_name" ]; then
+    echo "Sample already exists"
+    continue
+  fi
+
+  # if we reach here, the name is valid and the directory does not exist
+  break
+done
+
+# copy starter-sample to new sample directory
+cp -r starter-sample "samples/$sample_name"
+
+# party time
+echo "Sample created at samples/$sample_name"

starter-sample/.devcontainer/Dockerfile

@@ -0,0 +1,11 @@
+# Note: universal image is not compatible with the devcontainer tools.
+#       we use the typescript-node image instead here but should switch out per 
+#       project requirements. #REMOVE_ME_AFTER_EDITING
+
+# FROM mcr.microsoft.com/devcontainers/go:1.22-bookworm
+# FROM mcr.microsoft.com/devcontainers/python:3.12-bookworm
+# FROM mcr.microsoft.com/devcontainers/php:8.3-bookworm
+# FROM mcr.microsoft.com/devcontainers/ruby:3.2-bookworm
+# FROM mcr.microsoft.com/devcontainers/java:11-bookworm
+# FROM mcr.microsoft.com/devcontainers/rust:1-bookworm
+FROM mcr.microsoft.com/devcontainers/typescript-node:22-bookworm

starter-sample/.devcontainer/devcontainer.json

@@ -0,0 +1,10 @@
+{
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "features": {
+    "ghcr.io/defanglabs/devcontainer-feature/defang-cli:1.0.4": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  }
+}

starter-sample/.github/workflows/deploy.yaml

@@ -0,0 +1,20 @@
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v4
+
+    - name: Deploy
+      uses: DefangLabs/[email protected]

starter-sample/README.md

@@ -0,0 +1,35 @@
+# Starter Sample #REMOVE_ME_AFTER_EDITING
+
+This is a sample that shows the rough structure of an actual Defang sample. This top paragraph should give a bit of context about the project and what it does. The rest of the README should be a guide on how to use the sample. #REMOVE_ME_AFTER_EDITING
+
+## Prerequisites
+
+1. Download [Defang CLI](https://github.com/DefangLabs/defang)
+2. (Optional) If you are using [Defang BYOC](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) authenticated with your AWS account
+3. (Optional for local development) [Docker CLI](https://docs.docker.com/engine/install/)
+
+## Development
+
+To run the application locally, you can use the following command:
+
+```bash
+# This might be `docker compose -f compose.dev.yaml up` depending on the project. #REMOVE_ME_AFTER_EDITING
+docker compose up
+```
+
+## Deploying
+
+1. Open the terminal and type `defang login`
+2. Use the [`defang config`](https://docs.defang.io/docs/concepts/compose#configuration) command to setup environment variables. #REMOVE_ME_AFTER_EDITING
+3. Type `defang compose up` in the CLI.
+4. Your app will be running within a few minutes.
+
+---
+
+Title: Sample Title #REMOVE_ME_AFTER_EDITING
+
+Short Description: A short sentence or two describing the sample. #REMOVE_ME_AFTER_EDITING
+
+Tags: Tags, That, Are, Not, Programming, Languages #REMOVE_ME_AFTER_EDITING
+
+Languages: Programming, Languages, Used #REMOVE_ME_AFTER_EDITING

starter-sample/app/.dockerignore

@@ -0,0 +1,3 @@
+#REMOVE_ME_AFTER_EDITING - This Dockerignore is for a basic node app. Modify as needed.
+node_modules
+npm-debug.log

starter-sample/app/.gitignore

@@ -0,0 +1,2 @@
+#REMOVE_ME_AFTER_EDITING - This Dockerignore is for a basic node app. Modify as needed.
+node_modules

starter-sample/app/Dockerfile

@@ -0,0 +1,19 @@
+# A sample dockerfile for a Node.js application.
+# Replace with an appropriate Dockerfile for your application.
+#REMOVE_ME_AFTER_EDITING
+
+FROM node:20-bookworm-slim
+
+WORKDIR /app
+
+COPY package*.json ./
+
+RUN npm ci
+
+COPY . .
+
+RUN npm run build
+
+EXPOSE 3000
+
+CMD ["npm", "start"]