feat: add GitHub Actions workflow for MkDocs deployment

- fix: inject correct vars in go releaser builds
2025-10-22 21:01:57 +00:00 · 2025-02-24 02:27:06 +05:30
parent 1a7ee4d8c6
commit b44290a6f0
11 changed files with 188 additions and 22 deletions
--- a/.github/workflows/github-pages.yml
+++ b/.github/workflows/github-pages.yml
@@ -0,0 +1,31 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - run: pip install mkdocs-material
+
+      - run: |
+          if [ -f requirements.txt ]; then
+            pip install -r requirements.txt;
+          fi
+
+      - run: cd docs && mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/site
--- a/.gitignore
+++ b/.gitignore
@@ -6,4 +6,5 @@ libredesk
 libredesk.exe
 uploads
 .env
-dist/
+dist/
+.vscode/
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -24,11 +24,10 @@ builds:
    goarch:
      - amd64
      - arm64
-    binary: 'libredesk{{ if eq .Os "windows" }}.exe{{ end }}'
-    ldflags:
-      - -s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}
+    binary: "libredesk{{ if eq .Os \"windows\" }}.exe{{ end }}"
+    ldflags: "-s -w -X main.buildString={{ .Version }} (Commit: {{ .Commit }}, Build: {{ .Date }})"
    hooks:
-      post: make stuff BIN={{ .Path }}
+      post: "make stuff BIN={{ .Path }}"

  - id: "arm"
    main: ./cmd
@@ -44,11 +43,11 @@ builds:
    goarm:
      - 6
      - 7
-    binary: 'libredesk{{ if eq .Os "windows" }}.exe{{ end }}'
-    ldflags:
-      - -s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}
+    binary: "libredesk{{ if eq .Os \"windows\" }}.exe{{ end }}"
+    ldflags: "-s -w -X main.buildString={{ .Version }} (Commit: {{ .Commit }}, Build: {{ .Date }})"
    hooks:
-      post: make stuff BIN={{ .Path }}
+      post: "make stuff BIN={{ .Path }}"
+

 archives:
  - format: tar.gz
--- a/4
+++ b/4
@@ -36,7 +36,7 @@ frontend-build: install-deps
 .PHONY: run-backend
 run-backend:
 	@echo "→ Running backend..."
-	@go run cmd/*.go
+	CGO_ENABLED=0 go run -ldflags="-s -w -X 'main.buildString=${BUILDSTR}' -X 'main.frontendDir=frontend/dist'" cmd/*.go

 # Run the JS frontend server in development mode.
 .PHONY: run-frontend
@@ -51,7 +51,7 @@ run-frontend:
 backend-build: $(STUFFBIN)
 	@echo "→ Building backend..."
 	@CGO_ENABLED=0 go build -a\
-		-ldflags="-X 'main.buildString=${BUILDSTR}' -X 'main.buildDate=${LAST_COMMIT_DATE}' -s -w" \
+		-ldflags="-X 'main.buildString=${BUILDSTR}' -s -w" \
 		-o ${BIN} cmd/*.go

 # Main build target: builds both frontend and backend, then stuffs static assets into the binary.
--- a/config.sample.toml
+++ b/config.sample.toml
@@ -12,7 +12,7 @@ write_timeout = "5s"
 max_body_size = 500000000
 keepalive_timeout = "10s"

-# File upload provider to use.
+# File upload provider to use, either `fs` or `s3`.
 [upload]
 provider = "fs"

@@ -32,7 +32,7 @@ expiry = "6h"

 # Postgres.
 [db]
-# If using docker compose, use the service name as the host.
+# If using docker compose, use the service name as the host. e.g. db
 host = "127.0.0.1"
 port = 5432
 user = "postgres"
@@ -45,7 +45,7 @@ max_lifetime = "300s"

 # Redis.
 [redis]
-# If using docker compose, use the service name as the host.
+# If using docker compose, use the service name as the host. e.g. redis
 address = "127.0.0.1:6379"
 password = ""
 db = 0
--- a/docs/docs/developer-setup.md
+++ b/docs/docs/developer-setup.md
@@ -0,0 +1,31 @@
+# Developer Setup
+
+Libredesk is a monorepo with a Go backend and a Vue.js frontend. The frontend uses Shadcn for UI components.
+
+### Pre-requisites
+
+- `go`
+- `nodejs` (if you are working on the frontend) and `pnpm`
+- Postgres database (>= 13)
+
+### First time setup
+
+Clone the repository:
+
+```sh
+git clone https://github.com/abhinavxd/libredesk.git
+```
+
+1. Copy `config.toml.sample` as `config.toml` and add your config.
+2. Run `make` to build the libredesk binary. Once the binary is built, run `./libredesk --install` to run the DB setup and set the System user password.
+
+### Running the Dev Environment
+
+1. Run `make run` to start the libredesk backend dev server on `:9000`.
+2. Run `make run-frontend` to start the Vue frontend in dev mode using pnpm on `:8000`. Requests are proxied to the backend running on `:9000` check `vite.config.js` for the proxy config.
+
+---
+
+# Production Build
+
+Run `make` to build the Go binary, build the Javascript frontend, and embed the static assets producing a single self-contained binary, `libredesk`.
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -0,0 +1,13 @@
+# Introduction
+
+Libredesk is an open source, self-hosted customer support desk. Single binary app.
+
+
+<div style="border: 1px solid #ccc; padding: 1px; border-radius:5px; box-shadow: 2px 2px 5px rgba(0, 0, 0, 0.1); background-color: #fff;">
+    <a href="https://libredesk.io">
+        <img src="https://github.com/user-attachments/assets/55e0ec68-b624-4442-8387-6157742da253" alt="libredesk screenshot" style="display: block; margin: 0 auto;">
+    </a>
+</div>
+
+## Developers
+Libredesk is a free and open source software licensed under AGPLv3. If you are interested in contributing, check out the [GitHub repository](https://github.com/abhinavxd/libredesk) and refer to the [developer setup](developer-setup.md). The backend is written in Go and the frontend is Vue js 3 with Shadcn for UI components.
--- a/docs/docs/installation.md
+++ b/docs/docs/installation.md
@@ -0,0 +1,47 @@
+# Installation
+
+Libredesk is a single binary application that requires postgres and redis to run. You can install it using the binary or docker.
+
+## Binary
+
+1. Download the [latest release](https://github.com/abhinavxd/libredesk/releases) and extract the libredesk binary.
+2. `./libredesk --install` to install the tables in the Postgres DB (⩾ 13) and set the System user password.
+3. Run `./libredesk` and visit `http://localhost:9000` and login with the email `System` and the password you set during installation.
+
+!!! Tip
+    To set the System user password during installation, set the environment variables:
+    `LIBREDESK_SYSTEM_USER_PASSWORD=xxxxxxxxxxx ./libredesk --install`
+
+
+## Docker
+
+The latest image is available on DockerHub at `libredesk/llibredeskistmonk:latest`
+
+The recommended method is to download the [docker-compose.yml](https://github.com/abhinavxd/libredesk/blob/master/docker-compose.yml) file, customize it for your environment and then to simply run `docker compose up -d`.
+
+```shell
+# Download the compose file to the current directory.
+curl -LO https://github.com/abhinavxd/libredesk/raw/master/docker-compose.yml
+
+# Copy the config.sample.toml to config.toml and edit it as needed.
+cp config.sample.toml config.toml
+
+# Run the services in the background.
+docker compose up -d
+
+# Setting System user password.
+docker exec -it libredesk_app ./libredesk --set-system-user-password
+```
+
+Go to `http://localhost:9000` and login with the email `System` and the password you set using the `--set-system-user-password` command.
+
+---
+
+
+## Compiling from source
+
+To compile the latest unreleased version (`master` branch):
+
+1. Make sure `go`, `nodejs`, and `pnpm` are installed on your system.
+2. `git clone git@github.com:abhinavxd/libredesk.git`
+3. `cd libredesk && make`. This will generate the `libredesk` binary.
--- a/docs/docs/upgrade.md
+++ b/docs/docs/upgrade.md
@@ -0,0 +1,18 @@
+# Upgrade
+
+!!! Warning
+    Always take a backup of the Postgres database before upgrading Libredesk.
+
+## Binary
+- Stop running libredesk binary.
+- Download the [latest release](https://github.com/abhinavxd/libredesk/releases) and extract the libredesk binary and overwrite the previous version.
+- `./libredesk --upgrade` to upgrade an existing database schema. Upgrades are idempotent and running them multiple times have no side effects.
+- Run `./libredesk` again.
+
+## Docker
+
+```shell
+docker compose down app
+docker compose pull
+docker compose up app -d
+```
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -0,0 +1,34 @@
+site_name: Libredesk Documentation
+theme:
+  name: material
+  language: en
+  font:
+    text: Source Sans Pro
+    code: Roboto Mono
+    weights: 
+      - 400
+      - 700
+  direction: ltr
+  palette:
+    primary: white
+    accent: red
+  features:
+    - navigation.indexes
+    - navigation.sections
+    - content.code.copy
+  extra:
+    search:
+      language: en
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - toc:
+      permalink: true
+
+nav:
+  - Introduction: index.md
+  - Getting Started:
+      - Installation: installation.md
+      - Upgrade: upgrade.md
+  - Developer Setup: developer-setup.md
--- a/frontend/.vscode/extensions.json
+++ b/frontend/.vscode/extensions.json
@@ -1,8 +0,0 @@
-{
-  "recommendations": [
-    "Vue.volar",
-    "Vue.vscode-typescript-vue-plugin",
-    "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode"
-  ]
-}