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.
matheusgomes28 · May 15, 2024 · ab02517 · ab02517
1 parent 75f2cbe
commit ab02517
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 77 deletions.
diff --git a/.vscode/launch.json 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"
+            ]
+        },
+    ]
+}
diff --git 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/[email protected] 
-$ go install github.com/a-h/templ/cmd/[email protected] 
-$ go install github.com/cosmtrek/[email protected] 
+go install github.com/pressly/goose/v3/cmd/[email protected] 
+go install github.com/a-h/templ/cmd/[email protected] 
+go install github.com/cosmtrek/[email protected] 
 ```
 
 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.