Merge pull request #15 from Defacto2/v07

V07
Defacto2 · Jun 12, 2024 · a375e2c · a375e2c
2 parents 786093b + c6f79e7
commit a375e2c
Show file tree

Hide file tree

Showing 19 changed files with 594 additions and 773 deletions.
diff --git a/.github/workflows/go.yml → .github/workflows/gorelease.yml b/.github/workflows/go.yml → .github/workflows/gorelease.yml
@@ -4,31 +4,33 @@
 name: GoReleaser
 
 on:
-  pull_request:
   push:
     tags:
-      - "*"
+      - "*" # run on new tags
+
+permissions:
+  contents: write
 
 jobs:
   goreleaser:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - name: Checkout # required for the changelog to work correctly
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Git fetch
-        run: git fetch --force --tags
+
       - name: Setup Go with cache
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v5
         with:
-          go-version: '>=1.19.5'
+          go-version: ">=1.22.3"
           cache: true
-      - name: GoReleaser run
-        uses: goreleaser/goreleaser-action@v4
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
         with:
           distribution: goreleaser
           version: latest
-          args: release --rm-dist
+          args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/Taskfile.dist.yaml b/Taskfile.dist.yaml
@@ -64,26 +64,6 @@ tasks:
       - cmd: ./{{.BINNAME}} --version
         platforms: [linux, darwin]
       - cmd: echo "Done!"
-  build-snapshot:
-    aliases:
-      - "builds"
-    desc: "Build the release binary of the web server without a git version tag."
-    deps: [assets]
-    cmds:
-      - cmd: echo "Building snapshot..."
-      - cmd: goreleaser build --snapshot --clean --config init/.goreleaser.yaml
-      - cmd: echo "Done!"
-  build-release:
-    aliases:
-      - "release"
-    desc: "Build the release binary of the web server embeded with the git version tag."
-    deps: [assets]
-    cmds:
-      - cmd: echo "Git status results:"
-      - cmd: git status
-      - cmd: echo "Building snapshot..."
-      - cmd: goreleaser build --clean --config init/.goreleaser.yaml
-      - cmd: echo "Done!"
   assets:
     desc: "Build, compile and compress the web serve CSS and JS assets."
     cmds:
@@ -133,19 +113,43 @@ tasks:
     cmds:
       - air -c init/.air.toml
   pkg-patch:
+    aliases:
+      - "patch"
     silent: false
     desc: Update and apply patches to the web server dependencies.
     cmds:
       - cmd: go get -u=patch -x
       - cmd: go mod verify
       - cmd: go mod tidy
   pkg-update:
+    aliases:
+      - "update"
     silent: false
     desc: Update the web server dependencies.
     cmds:
       - cmd: go get -u -x
       - cmd: go mod verify
       - cmd: go mod tidy
+  pkg-snapshot:
+    aliases:
+      - "snap"
+    desc: "Build the release package of the web server without a git version tag."
+    deps: [assets]
+    cmds:
+      - cmd: echo "Building snapshot..."
+      - cmd: goreleaser build --snapshot --clean --config init/.goreleaser.yaml
+      - cmd: echo "Done!"
+  pkg-release:
+    aliases:
+      - "release"
+    desc: "Build the release package of the web server embeded with the git version tag."
+    deps: [assets]
+    cmds:
+      - cmd: echo "Git status results:"
+      - cmd: git status
+      - cmd: echo "Building snapshot..."
+      - cmd: goreleaser build --clean --config init/.goreleaser.yaml
+      - cmd: echo "Done!"
   ver:
     silent: false
     desc: Print the versions of the build and compiler tools.
@@ -165,7 +169,7 @@ tasks:
     desc: "Initialise this project for the first time after a git clone."
     cmds:
       - cmd: go install mvdan.cc/gofumpt@latest
-      - cmd: go install github.com/cosmtrek/air@latest
+      - cmd: go install github.com/air-verse/air@latest
       - cmd: go install github.com/goreleaser/goreleaser@latest
       - cmd: go install github.com/evanw/esbuild/cmd/esbuild@latest
       - cmd: go install github.com/volatiletech/sqlboiler/v4@latest

diff --git a/docs/README.md b/docs/README.md
@@ -1,5 +1,9 @@
 # Defacto2, <small>web application server</small>
 
+[![Go Reference](server.svg)](https://pkg.go.dev/github.com/Defacto2/server)
+[![License](license.svg)](./LICENSE)
+[![Go Report Card](https://goreportcard.com/badge/github.com/Defacto2/server)](https://goreportcard.com/report/github.com/Defacto2/server)
+
 ```
       ·      ▒██▀ ▀       ▒██▀ ▀              ▀ ▀▒██             ▀ ▀███ ·
       : ▒██▀ ▓██ ▒██▀▀██▓ ▓██▀▀▒██▀▀███ ▒██▀▀██▓ ▓██▀ ▒██▀▀███ ▒██▀▀▀▀▀ :
@@ -15,11 +19,9 @@ The application relies on a [PostgreSQL](https://www.postgresql.org/) database s
 
 All configurations and modifications to this web application's default settings are through system environment variables.
 
-While you can compile the application to target Windows environments, it is ill-advised as it needs to work correctly with NTFS file paths. Instead, it is advisable to use Windows Subsystem for Linux.
-
 ## Download
 
-Currently the application is available as a [standalone binary for Linux](https://github.com/Defacto2/server/releases/download/v0.5.0/df2-server_0.5.0_linux.zip).
+Currently the application is available as a [standalone binary for Linux](https://github.com/Defacto2/server/releases/download/v0.6.0/df2-server_0.6.0_linux.zip).
 
 ## Installation
 
@@ -30,8 +32,8 @@ Installation instructions are provided for [Ubuntu Server](https://ubuntu.com/se
 cd ~
 
 # download and unzip the latest release
-wget https://github.com/Defacto2/server/releases/latest/download/df2-server_0.5.0_linux.zip
-unzip df2-server_0.5.0_linux.zip
+wget https://github.com/Defacto2/server/releases/latest/download/df2-server_0.6.0_linux.zip
+unzip df2-server_0.6.0_linux.zip
 
 # make the binary executable
 sudo chmod +x df2-server
@@ -63,6 +65,12 @@ There are examples of the environment variables in the [example .env](../init/ex
 
 The source code requires a local [installation of Go](https://go.dev/doc/install) version 1.22 or newer. 
 
+```sh
+$ go version
+
+> go version go1.22.3 linux/amd64
+```
+
 > [!IMPORTANT]
 > While you can compile the application to target Windows environments, it will not function correctly with NTFS file paths. Instead, it is advisable to use Windows Subsystem for Linux.
 
@@ -77,14 +85,23 @@ cd server
 
 # optional, download the dependencies
 go mod download
+```
 
-# test the application
-go run . --version
+Test the application.
+
+```sh
+$ go run . --version
+
+> Defacto2 web application version n/a (not a build) for Linux on Intel/AMD 64
 ```
 
 ## Source code tasks
 
-The repository is configured to use the [Task](https://taskfile.dev/installation/) application which needs local installation.
+The repository is configured to use the [Task](https://taskfile.dev/installation/) application which needs local installation. The following of tools are expected to be installed on the local machine.
+
+1. [Task](https://taskfile.dev/installation/) is a task runner / build tool.
+2. [golangci-lint](https://golangci-lint.run/) is a Go linters aggregator.
+3. [GoReleaser](https://goreleaser.com/install/) is a release automation tool for Go projects.
 
 ### First time initialization
 
@@ -104,21 +121,21 @@ task ver
 The list of available tasks can be shown.
 
 ```sh
-$ task --list-all
+$ task # --list-all
 
 task: Available tasks for this project:
 * _init:                Initialise this project for the first time after a git clone.
 * assets:               Build, compile and compress the web serve CSS and JS assets.
 * build:                Build the binary of the web server.
 * build-race:           Build the binary of the web server with race detection.
-* build-release:        Build the release binary of the web server embeded with the git version tag.  
-* build-snapshot:       Build the release binary of the web server without a git version tag. 
 * default:              Task runner for the Defacto2 web server source code.
 * doc:                  Generate and browse the application module documentation.
 * lint:                 Runs the go formatter and lints the source code.
 * lint+:                Runs the deadcode and betteralign linters on the source code.
 * nil:                  Run the static analysis techniques to catch Nil dereferences.
 * pkg-patch:            Update and apply patches to the web server dependencies.
+* pkg-release:          Build the release binary of the web server embeded with the git version tag.  
+* pkg-snapshot:         Build the release binary of the web server without a git version tag. 
 * pkg-update:           Update the web server dependencies.
 * serve-dev:            Run the internal web server in development mode with live reload.
 * serve-prod:           Run the internal web server with live reload.
@@ -127,8 +144,51 @@ task: Available tasks for this project:
 * ver:                  Print the versions of the build and compiler tools.
 ```
 
-### Configuration
+### Configurations
 
+As the application relies on environmental variables for configuration, the Taskfile can use a dot-env file to read in variables for use on tasks.
+
+For example, you can configure various variables while running the `task serve-dev` or `task serve-prod` tasks to point to the downloads, image screenshots, image thumbnails, and a customized database connection URL.
+
+```sh
+# change to the server repository directory init directory
+cd server/init
+
+# copy the example .env file to the local .env file
+cp example.env.local .env.local
+
+# edit the .env file to set the environment variables
+nano .env.local
+```
+
+An example, the `.env.local` file can be configured as follows.
+
+```ini
+# ==============================================================================
+#  These are the directory paths serving static files for the artifacts.
+#  All directories must be absolute paths and any empty values will disable the
+#  relevent feature. For example, an invalid D2_DIR_DOWN will disable the 
+#  artifact downloads.
+#  The directories must be readable and writable by the web server.
+# ==============================================================================
+
+# List the directory path that holds the named UUID files for the artifact downloads.
+D2_DIR_DOWNLOAD=/home/defacto2/downloads
+
+# List the directory path that holds the named UUID files for the artifact images.
+D2_DIR_PREVIEW=/home/defacto2/previews
+
+# List the directory path that holds the named UUID files for the artifact thumbnails.
+D2_DIR_THUMBNAIL=/home/defacto2/thumbnails
+
+# ==============================================================================
+#  These are the PostgreSQL database connection settings.
+#  The database is required for accessing and displaying the artifact data.
+# ==============================================================================
+
+# The connection string to the PostgreSQL database.
+D2_DATABASE_URL=postgres://root:example@localhost:5432/defacto2_ps
+```
 
 ### Run the development server
 
@@ -169,33 +229,57 @@ The source code has a test suite that can be run.
 task test
 ```
 
+Or check for race conditions in the test suite.
+
+```sh
+task testr
+```
+
 ### Documentation
 
-The application configuration documentation can be generated and viewed in a web browser.
+The application configuration documentation can be modified in [`doc.go`](../doc.go) and the changes regenerated and [previewed in a web browser](http://localhost:8090).
 
 ```sh
 task doc
 ```
 
-Or check for race conditions in the test suite.
+```go
+// Copyright © 2023-2024 Ben Garrett. All rights reserved.
 
-```sh
-task testr
+/*
+
+The [Defacto2] application is a self-contained web server first devised in 2023.
+It is built with the Go language and can be easily compiled for significant server 
 ```
 
 ### Building the source code
 
+The source code can be built into a binary for the local machine.
+
+```sh
+task build
+
+# or to build with race detection
+task buildx
+```
+
+The resulting `df2-server` binary is built in the repository root directory.
+
+### Packaging a release
+
 Building the distribution package for the server application is done using a local installation of  [GoReleaser](https://goreleaser.com/install/).
 
-To build a snapshot binary for the local machine without a version tag.
+#### Test a package release
+
+To package a snapshot binary for the local machine without a version tag.
 
 ```sh
-task build-snapshot
+task pkg-snapshot
 ```
 
 The resulting binary is in the `dist/` directory in the repository root.
 
-### Building a release binary
+#### Packaging a release
 
 ```sh
 # check the configuration file
@@ -206,8 +290,37 @@ git tag -a v1.0.1 -m "First update to the release version."
 git push origin v1.0.1
 
 # build the release binary
-task build-release
+task pkg-release
 ```
 
 The resulting built package is found in the `dist/` directory in the repository root.
 
+### Modifying the database schema
+
+The web application relies on an Object-relational mapping (ORM) implementation provided by [SQLBoiler](https://github.com/volatiletech/sqlboiler) to simplify development. If the database schema ever changes with a new table column, a modification of an existing column type, or a name change, the ORM code generation requires a rerun.
+
+After modifying the database schema, confirm the local development database connection settings are correct in the SQLBoiler [settings file](../init/.sqlboiler.toml) `init/.sqlboiler.toml`.
+
+```toml
+[psql]
+schema = "public"
+dbname = "defacto2_ps"
+host = "localhost"
+port = 5432
+user = "root"
+pass = "example"
+sslmode = "disable"
+
+[auto-columns]
+created = "createdat"
+updated = "updatedat"
+deleted = "deletedat"
+```
+
+Then in the root of the repository, run go generate.
+
+```sh
+go generate
+```
+
+The generated code is found in the `internal/postgres/model/` directory and is ready for use.