diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml new file mode 100644 index 0000000..be6e475 --- /dev/null +++ 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 diff --git a/.gitignore b/.gitignore index 18ae409..121f106 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,5 @@ libredesk libredesk.exe uploads .env -dist/ \ No newline at end of file +dist/ +.vscode/ diff --git a/.goreleaser.yaml b/.goreleaser.yaml index aabb09f..bfac224 100644 --- 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 diff --git a/Makefile b/Makefile index f2715b3..0bc2a90 100644 --- a/Makefile +++ b/Makefile @@ -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. diff --git a/config.sample.toml b/config.sample.toml index 3da7e1c..2726843 100644 --- 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 diff --git a/docs/docs/developer-setup.md b/docs/docs/developer-setup.md new file mode 100644 index 0000000..5bf9402 --- /dev/null +++ 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`. \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..4584dbd --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,13 @@ +# Introduction + +Libredesk is an open source, self-hosted customer support desk. Single binary app. + + +
+ + libredesk screenshot + +
+ +## 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. \ No newline at end of file diff --git a/docs/docs/installation.md b/docs/docs/installation.md new file mode 100644 index 0000000..e9c19dc --- /dev/null +++ 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. diff --git a/docs/docs/upgrade.md b/docs/docs/upgrade.md new file mode 100644 index 0000000..24f533f --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..e3cd2ea --- /dev/null +++ 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 \ No newline at end of file diff --git a/frontend/.vscode/extensions.json b/frontend/.vscode/extensions.json deleted file mode 100644 index 009a534..0000000 --- a/frontend/.vscode/extensions.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "recommendations": [ - "Vue.volar", - "Vue.vscode-typescript-vue-plugin", - "dbaeumer.vscode-eslint", - "esbenp.prettier-vscode" - ] -}