From ab025178e9176016d791c18e730cfac1cf68277b Mon Sep 17 00:00:00 2001 From: matheusgomes28 Date: Wed, 15 May 2024 21:27:20 +0100 Subject: [PATCH] More improvements to README.md and usage * Removed duplicate development sections. * Removed duplicate dependencies sections. * Added comment regarding debugging with provided launch.json * Added .vscode/launch.json file with basic debugging config. --- .vscode/launch.json | 34 +++++++++++++++ README.md | 102 +++++++++++--------------------------------- 2 files changed, 59 insertions(+), 77 deletions(-) create mode 100644 .vscode/launch.json diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..4b515d9 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,34 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + { + "name": "CmsApp", + "type": "go", + "request": "launch", + "mode": "auto", + "program": "${workspaceFolder}/cmd/urchin", + "cwd": "${workspaceFolder}", + "envFile": "${workspaceFolder}/envfile", + "args": [ + "--config", + "${workspaceFolder}/urchin_config.toml" + ] + }, + { + "name": "AdminApp", + "type": "go", + "request": "launch", + "mode": "auto", + "program": "${workspaceFolder}/cmd/urchin-admin", + "cwd": "${workspaceFolder}", + "envFile": "${workspaceFolder}/envfile", + "args": [ + "--config", + "${workspaceFolder}/urchin_config.toml" + ] + }, + ] +} \ No newline at end of file diff --git a/README.md b/README.md index 310144f..294d831 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,6 @@ commands. - [ ] **Menus**: TODO - [ ] **Live Reload** through the use of `air`. -## Installation - -Ensure you have Golang installed on your system before proceeding with the installation. - ## Running Urchin Urchin is developed with Golang, so make sure you have a recent enough @@ -114,6 +110,11 @@ cd migrations GOOSE_DRIVER="mysql" GOOSE_DBSTRING="root:root@/urchin" goose up ``` +Once the database is up and migrated, you can run Urchin with your +favourite debugger setup. For the `Vscode` and `delve` setup, we +have provided the file `.vscode/launch.json` so you should just be +able to select the (admin) app from the `Vscode` debugging dropdown. + ## Architecture Currently, the architecture of `urchin` is still in its early days. @@ -135,13 +136,6 @@ database: - **cards**: Still TODO. Need to decide how this will allow users to display menu-like pages with cards. -## Dependencies - -Urchin relies on the following Golang dependencies: - -- [Gin](github.com/gin-gonic/gin) as the web framework for Golang. -- [ZeroLog](https://github.com/rs/zerolog) for logging. - ## Configuration The runtime configuration can be done through a [toml](https://toml.io/en/) configuration file or by setting the mandatory environment variables (*fallback*). This approach was chosen because configuration via toml supports advanced features (i.e. *relationships*, *arrays*, etc.). The `.dev.env`-file is used to configure the development database through `docker-compose`. @@ -157,34 +151,24 @@ database_password = "urchinpw" # Password for the database user database_port = 3306 # The port to use for the application database_name = "urchin" # The database to use for Urchin webserver_port = 8080 # The application port Urchin should use +admin_port = 8081 # The port in which the admin app will be running image_dir = "./images" # Directory to use for storing uploaded images. + +# Navbar section specifies the links that appear on +# the navbar +[navbar] +links = [ + { name = "Home", href = "/", title = "Homepage" }, + { name = "About", href = "/about", title = "About page" }, + { name = "Services", href = "/services", title = "Services page" }, + { name = "Images", href = "/images", title = "Images page" }, + { name = "Contact", href = "/contact", title = "Contacts page" }, +] ``` **Important**: The configuration values above are used to start-up the local development database. -### Environment variables configuration (fallback) - -If chosen, by setting the following environment variables the application can be started without providing a toml configuration file. - -- `URCHIN_DATABASE_ADDRESS` should contain the database addres, - e.g. `localhost`. -- `URCHIN_DATABASE_PORT` should be the connection port to the - database. For example `3306`. -- `URCHIN_DATABASE_USER` is the database username. -- `URCHIN_DATABASE_PASSWORD` needs to contain the database password for the given user. -- `URCHIN_DATABASE_NAME` sets the name of the database Urchin will use. -- `URCHIN_WEBSERVER_PORT` the port the application should run on. -- `URCHIN_IMAGE_DIRECTORY` the directory images should be stored to if uploaded to Urchin - -## Development - -To ease up the development process, Docker is highly recommended. This way you can use the `docker/mariadb.yml` to set up a predefined MariaDB database server. The docker-compose file references the `.dev.env` and creates the Urchin database and an application user. - -```bash -$ docker-compose -f docker/mariadb.yml up -d -``` - -### Dependencies +## Dependencies For the development of Urchin, you require additional dependecies, that can easily be installed with go. @@ -196,53 +180,17 @@ For the development of Urchin, you require additional dependecies, that can easi - [Air](https://github.com/cosmtrek/air) (for hot-reloading Go projects) To install the development dependencies simply execute the following Go commands: + ```bash -$ go install github.com/pressly/goose/v3/cmd/goose@v3.18.0 -$ go install github.com/a-h/templ/cmd/templ@v0.2.543 -$ go install github.com/cosmtrek/air@v1.49.0 +go install github.com/pressly/goose/v3/cmd/goose@v3.18.0 +go install github.com/a-h/templ/cmd/templ@v0.2.543 +go install github.com/cosmtrek/air@v1.49.0 ``` After installing the required dependecies and starting the pre-configured database, you can simply execute the following command to execute the migration of the database for development purposes. ```bash -$ source .dev.env # sets the environment variable for the goose command. -$ cd migrations/ -$ GOOSE_DRIVER="mysql" GOOSE_DBSTRING="$MARIADB_USER:$MARIADB_PASSWORD@tcp($MARIADB_ADDRESS:$MARIADB_PORT)/$MARIADB_DATABASE" goose up -``` - -### Launching & Debugging - -To debug the application or simply running it from within VSCode create a `launch.json` with the following configuration: - -```json -{ - ..., - "configurations": [ - { - "name": "Urchin", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/cmd/urchin/main.go", - "cwd": "${workspaceFolder}", - "args": [ - "--config", - "urchin_config.toml" - ] - }, - { - "name": "Urchin Admin", - "type": "go", - "request": "launch", - "mode": "auto", - "program": "${workspaceFolder}/cmd/urchin-admin/main.go", - "cwd": "${workspaceFolder}", - "args": [ - "--config", - "urchin_config.toml" - ] - } - ] -} +source .dev.env # sets the environment variable for the goose command. +cd migrations/ +GOOSE_DRIVER="mysql" GOOSE_DBSTRING="$MARIADB_USER:$MARIADB_PASSWORD@tcp($MARIADB_ADDRESS:$MARIADB_PORT)/$MARIADB_DATABASE" goose up ``` -However, the [Go-Extension](https://marketplace.visualstudio.com/items?itemName=golang.Go) must be installed before you can use these launch configurations.