docs: improve deployment posts

Author: ivictbor

adminforth/documentation/blog/2024-11-14-compose-ec2-deployment-ci/index.md

@@ -22,19 +22,18 @@ Create file `Dockerfile` in `myadmin`:
 
 ```Dockerfile title="./myadmin/Dockerfile"
 # use the same node version which you used during dev
-FROM node:20-alpine
+FROM node:22-alpine
 WORKDIR /code/
 ADD package.json package-lock.json /code/
 RUN npm ci  
 ADD . /code/
 RUN --mount=type=cache,target=/tmp npx tsx bundleNow.ts
-CMD ["npm", "run", "startLive"]
+CMD ["sh", "-c", "npm run migrate:prod && npm run prod"]
 ```
 
-
 ## Step 2 - compose.yml
 
-create folder `deploy` and create file `compose.yml` inside:
+Create folder `deploy` and create file `compose.yml` inside:
 
 ```yml title="deploy/compose.yml"
 
@@ -51,10 +50,10 @@ services:
       - "/var/run/docker.sock:/var/run/docker.sock:ro"
 
   myadmin:
-    build: ./myadmin
+    build: ../myadmin
     restart: always
     env_file:
-      - ./myadmin/.env
+      - ./myadmin/.env.secrets.prod
     volumes:
       - myadmin-db:/code/db
     labels:
@@ -88,12 +87,12 @@ Create `deploy/.gitignore` file with next content:
 *.tfstate.*
 *.tfvars
 tfplan
+.env.secrets.prod
 ```
 
 ## Step 5 - Main terraform file main.tf
 
 
-
 First of all install Terraform as described here [terraform installation](https://developer.hashicorp.com/terraform/install#linux).
 
 
@@ -102,7 +101,7 @@ Create file `main.tf` in `deploy` folder:
 ```hcl title="deploy/main.tf"
 
 locals {
-  app_name = "<your_app_name>"
+  app_name = "<your_app_name>" # replace with your app name
   aws_region = "eu-central-1"
 }
 
@@ -230,13 +229,34 @@ resource "aws_instance" "app_instance" {
     systemctl start docker
     systemctl enable docker
     usermod -a -G docker ubuntu
+
+    echo "done" > /home/ubuntu/user_data_done
   EOF
 
   tags = {
     Name = "${local.app_name}-instance"
   }
 }
 
+resource "null_resource" "wait_for_user_data" {
+  provisioner "remote-exec" {
+    inline = [
+      "echo 'Waiting for EC2 software install to finish...'",
+      "while [ ! -f /home/ubuntu/user_data_done ]; do echo '...'; sleep 2; done",
+      "echo 'EC2 software install finished.'"
+    ]
+
+    connection {
+      type        = "ssh"
+      user        = "ubuntu"
+      private_key = file("./.keys/id_rsa")
+      host        = aws_eip_association.eip_assoc.public_ip
+    }
+  }
+
+  depends_on = [aws_instance.app_instance]
+}
+
 resource "null_resource" "sync_files_and_run" {
   # Use rsync to exclude node_modules, .git, db
   provisioner "local-exec" {
@@ -262,16 +282,12 @@ resource "null_resource" "sync_files_and_run" {
   # Run docker compose after files have been copied
   provisioner "remote-exec" {
     inline = [
-      # fail bash specially and intentionally to stop the script on error
-      "bash -c 'while ! command -v docker &> /dev/null; do echo \"Waiting for Docker to be installed...\"; sleep 1; done'",
-      "bash -c 'while ! docker info &> /dev/null; do echo \"Waiting for Docker to start...\"; sleep 1; done'",
-      
       # please note that prune might destroy build cache and make build slower, however it releases disk space
       "docker system prune -f",
       # "docker buildx prune -f --filter 'type!=exec.cachemount'",
       "cd /home/ubuntu/app/deploy",
       # COMPOSE_FORCE_NO_TTY is needed to run docker compose in non-interactive mode and prevent stdout mess up
-      "COMPOSE_FORCE_NO_TTY=1 docker compose -p app -f compose.yml up --build -d"
+      "COMPOSE_BAKE=true docker compose --progress=plain -p app -f compose.yml up --build -d"
     ]
 
     connection {
@@ -287,7 +303,7 @@ resource "null_resource" "sync_files_and_run" {
     always_run = timestamp()
   }
 
-  depends_on = [aws_instance.app_instance, aws_eip_association.eip_assoc]
+  depends_on = [null_resource.wait_for_user_data, aws_eip_association.eip_assoc]
 }
 
 
@@ -310,6 +326,10 @@ resource "aws_s3_bucket_lifecycle_configuration" "terraform_state" {
     status = "Enabled"
     id = "Keep only the latest version of the state file"
 
+    filter {
+      prefix = ""
+    }
+
     noncurrent_version_expiration {
       noncurrent_days = 30
     }
@@ -333,8 +353,6 @@ resource "aws_s3_bucket_server_side_encryption_configuration" "terraform_state"
     }
   }
 }
-
-
 ```
 
 > 👆 Replace `<your_app_name>` with your app name (no spaces, only underscores or letters)
@@ -424,6 +442,11 @@ jobs:
         with:
           terraform_version: 1.10.1 
       - run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner."
+      - name: Prepare env
+        run: |
+          echo "ADMINFORTH_SECRET=$VAULT_ADMINFORTH_SECRET" > deploy/.env.secrets.prod
+        env:
+          VAULT_ADMINFORTH_SECRET: ${{ secrets.VAULT_ADMINFORTH_SECRET }}
       - name: Start building
         env:
           VAULT_AWS_ACCESS_KEY_ID: ${{ secrets.VAULT_AWS_ACCESS_KEY_ID }}
@@ -477,6 +500,6 @@ Go to your GitHub repository, then `Settings` -> `Secrets` -> `New repository se
 - `VAULT_AWS_SECRET_ACCESS_KEY` - your AWS secret key
 - `VAULT_SSH_PRIVATE_KEY` - make `cat ~/.ssh/id_rsa` and paste to GitHub secrets
 - `VAULT_SSH_PUBLIC_KEY` - make `cat ~/.ssh/id_rsa.pub` and paste to GitHub secrets
-
+- `VAULT_ADMINFORTH_SECRET` - your AdminForth secret - random string, for example `openssl rand -base64 32 | tr -d '\n'`
 
 Now you can push your changes to GitHub and see how it will be deployed automatically.

adminforth/documentation/blog/2025-02-19-compose-ec2-deployment-ci-registry/index.md

@@ -35,7 +35,6 @@ Previously we had a blog post about [deploying AdminForth to EC2 with Terraform
 
 So obviously to solve this problem we need to move the build process to CI, however it introduces new chellenges and we will solve them in this post.
 
-
 Quick difference between approaches from previous post and current post:
 
 | Feature | Without Registry | With Registry |
@@ -44,8 +43,11 @@ Quick difference between approaches from previous post and current post:
 | How Docker build layers are cached | Cache is stored on EC2 | GitHub actions has no own Docker cache out of the box, so it should be stored in dedicated place (we use self-hosted registry on the EC2 as it is free) |
 | Advantages | Simpler setup with less code (we don't need code to run and secure registry, and don't need extra cache setup as is naturally persisted on EC2). | Build is done on CI, so EC2 server is not overloaded. For most cases CI builds are faster than on EC2. Plus time is saved because we don't need to rsync source code to EC2 |
 | Disadvantages | Build on EC2 requires additional server RAM / overloads CPU | More terraform code is needed. Registry cache might require small extra space on EC2. Complexities to make it run from both local machine and CI |
-| Initial build time *from local machine up to working state | 2m 48.412s |  |
-| Rebuild time *from local machine, no docker cache changed `index.ts`| 0m 34.520s |  |
+| Initial build time\* | 2m 48.412s | 3m 13.541s |
+| Rebuild time (changed `index.ts`)\*| 0m 34.520s | 0m 51.653s |
+
+<sub>\* All tests done from local machine (Intel(R) Core(TM) Ultra 9 185H, Docker Desktop/WSL2 64 GB RAM, 300Mbps up/down) up to working state</sub>
+
 
 ## Chellenges when you build on CI
 
@@ -117,13 +119,13 @@ Create file `Dockerfile` in `myadmin`:
 
 ```Dockerfile title="./myadmin/Dockerfile"
 # use the same node version which you used during dev
-FROM node:20-alpine
+FROM node:22-alpine
 WORKDIR /code/
 ADD package.json package-lock.json /code/
 RUN npm ci  
 ADD . /code/
 RUN --mount=type=cache,target=/tmp npx tsx bundleNow.ts
-CMD ["npm", "run", "migrateLiveAndStart"]
+CMD ["sh", "-c", "npm run migrate:prod && npm run prod"]
 ```
 
 ### Step 1.1 - Create bundleNow.ts
@@ -159,9 +161,18 @@ Make sure you are not calling bundleNow in `index.ts` file for non-development m
 ```json title="./myadmin/package.json"
 ...
 "scripts": {
-  ...
-  "migrateLiveAndStart": "npx --yes prisma migrate deploy && tsx index.ts",
-  ...
+  "scripts": {
+    "dev": "npm run _env:dev -- tsx watch index.ts",
+    "prod": "npm run _env:prod -- tsx index.ts",
+    "start": "npm run dev",
+
+    "makemigration": "npm run _env:dev -- npx --yes prisma migrate dev --create-only",
+    "migrate:local": "npm run _env:dev -- npx --yes prisma migrate deploy",
+    "migrate:prod": "npm run _env:prod -- npx --yes prisma migrate deploy",
+
+    "_env:dev": "dotenvx run -f .env -f .env.local --",
+    "_env:prod": "dotenvx run -f .env.prod --"
+  },
 }
 ...
 ```
@@ -197,7 +208,7 @@ services:
     pull_policy: always
     restart: always
     env_file:
-      - .env.secrets.live
+      - .env.secrets.prod
     environment:
       - NODE_ENV=production
       - DATABASE_URL=sqlite://.db.sqlite
@@ -248,7 +259,7 @@ Create `deploy/.gitignore` file with next content:
 *.tfstate.*
 *.tfvars
 tfplan
-.env.secrets.live
+.env.secrets.prod
 ```
 
 ## Step 6 - buildx bake file
@@ -288,7 +299,6 @@ locals {
   aws_region = "us-east-1"
 }
 
-
 provider "aws" {
   region = local.aws_region
   profile = "myaws"
@@ -308,7 +318,6 @@ data "aws_vpc" "default" {
   default = true
 }
 
-
 resource "aws_eip" "eip" {
  domain = "vpc"
 }
@@ -783,7 +792,7 @@ jobs:
 
       - name: Prepare env
         run: |
-          echo "ADMINFORTH_SECRET=$VAULT_ADMINFORTH_SECRET" > deploy/.env.secrets.live
+          echo "ADMINFORTH_SECRET=$VAULT_ADMINFORTH_SECRET" > deploy/.env.secrets.prod
         env:
           VAULT_ADMINFORTH_SECRET: ${{ secrets.VAULT_ADMINFORTH_SECRET }}
 
@@ -832,9 +841,9 @@ Now open GitHub actions file and add it to the `env` section:
 ```yml title=".github/workflows/deploy.yml"
       - name: Prepare env
         run: |
-          echo "ADMINFORTH_SECRET=$VAULT_ADMINFORTH_SECRET" > deploy/.env.secrets.live
+          echo "ADMINFORTH_SECRET=$VAULT_ADMINFORTH_SECRET" > deploy/.env.secrets.prod
 //diff-add
-          echo "OPENAI_API_KEY=$VAULT_OPENAI_API_KEY" >> deploy/.env.secrets.live
+          echo "OPENAI_API_KEY=$VAULT_OPENAI_API_KEY" >> deploy/.env.secrets.prod
 //diff-add
         env:
           VAULT_ADMINFORTH_SECRET: ${{ secrets.VAULT_ADMINFORTH_SECRET }}
@@ -948,6 +957,7 @@ Create folder `deploy/.local` and create next files:
 ```sh title=deploy/.local/create-builder.sh
 #!/bin/bash
 cd "$(dirname "$0")"
+docker buildx rm mybuilder || true
 docker buildx create --name mybuilder --driver docker-container   --use --config ./buildkitd.toml
 ```
 
@@ -957,9 +967,9 @@ Now create builder:
 bash .local/create-builder.sh
 ```
 
-#### 2. You need to deliver envs locally
+#### 2. You need to deliver same secrets from local machine as from CI vault
 
-Create file `deploy/.env.secrets.live` with next content:
+Create file `deploy/.env.secrets.prod` with next content:
 
 ```sh
 ADMINFORTH_SECRET=<your secret>
@@ -969,7 +979,8 @@ Please note that if you are running builds both from GA and local, the `ADMINFOR
 
 #### 2. You need to add app.server.local to your hosts file (Windows/WSL only)
 
-> This step is not needed on Linux / Mac because 
+> This step is not needed on Linux / Mac because teraform provisioner will autiomatically add it to `/etc/hosts` file.
+> However in WSL we can't modify Windows native hosts file, so we need to do it manually.
 
 In power shell run 
 
@@ -981,4 +992,15 @@ Check your public IP in Terraform output and add
 
 ```
 <your public ip> appserver.local
-```
+```
+
+> Bad news is that instance public IP will be known only after first run, so some steps would fail because there will be no hosts mapping. However since EC2 provisioning takes some time it is even possible to copy IP from terminal and inser it to hosts file from first run 🤪
+
+
+### 3. Using local build from multiple projects
+
+The easiest way would be probably to rename `appserver.local` to unique name for each project.
+
+Then you can put all certificate mappings to a `buildkitd.toml` and move it along with `create-builder.sh` script to a common folder, e.g. home
+
+