github.com/jamiefdhurst/journal@v0.9.2/README.md (about) 1 # Journal 2 3  4 [](https://github.com/jamiefdhurst/journal/actions/workflows/build.yml) 5 [](https://github.com/jamiefdhurst/journal/releases) 6 7 A simple web-based journal written in Go. You can post, edit and view entries, 8 with the addition of an API. 9 10 It makes use of a SQLite database to store the journal entries. 11 12 [API Documentation](api/README.md) 13 14 ## Purpose 15 16 Journal serves as an easy-to-read and simple Golang program for new developers 17 to try their hand at modifying, extending and playing with. It deliberately has 18 only one dependency to ensure that the full end-to-end flow of the system can 19 be understood through standard Golang libraries. 20 21 It's also a nice little Journal that you can use to keep your thoughts in, or 22 as a basic blog platform. 23 24 ## Installation and Setup (local method) 25 26 1. Clone the repository. 27 2. Make sure the `$GOPATH/data` directory exists. 28 3. Run `go get ./...` to install dependencies 29 4. Run `go build journal.go` to create the executable. 30 5. Run `./journal` to load the application on port 3000. You should now be able 31 to fully access it at [http://localhost:3000](http://localhost:3000) 32 33 ## Installation and Setup (Docker method) 34 35 _Please note: you will need Docker installed on your local machine._ 36 37 1. Clone the repository to your chosen folder. 38 2. Build the container with `docker build -t journal:latest .` 39 3. Run the following to load the application and serve it on port 3000. You 40 should now be able to fully access it at [http://localhost:3000](http://localhost:3000) 41 42 ```bash 43 docker run --rm -v ./data:/go/data -p 3000:3000 -it journal:latest 44 ``` 45 46 ## Environment Variables 47 48 * `J_ARTICLES_PER_PAGE` - Articles to display per page, default `20` 49 * `J_CREATE` - Set to `0` to disable article creation 50 * `J_DB_PATH` - Path to SQLite DB - default is `$GOPATH/data/journal.db` 51 * `J_DESCRIPTION` - Set the HTML description of the Journal 52 * `J_EDIT` - Set to `0` to disable article modification 53 * `J_GA_CODE` - Google Analytics tag value, starts with `UA-`, or ignore to disable Google Analytics 54 * `J_GIPHY_API_KEY` - Set to a GIPHY API key to use, or ignore to disable GIPHY 55 * `J_PORT` - Port to expose over HTTP, default is `3000` 56 * `J_TITLE` - Set the title of the Journal 57 58 To use the API key within your Docker setup, include it as follows: 59 60 ```bash 61 docker run --rm -e J_GIPHY_API_KEY=... -v ./data:/go/data -p 3000:3000 -it journal:latest 62 ``` 63 64 ## Layout 65 66 The project layout follows the standard set out in the following document: 67 [https://github.com/golang-standards/project-layout](https://github.com/golang-standards/project-layout) 68 69 * `/api` - API documentation 70 * `/internal/app/controller` - Controllers for the main application 71 * `/internal/app/model` - Models for the main application 72 * `/internal/app/router` - Implementation of router for given app 73 * `/pkg/adapter` - Adapters for connecting to external services 74 * `/pkg/controller` - Controller logic 75 * `/pkg/database` - Database connection logic 76 * `/pkg/router` - Router for handling services 77 * `/test` - API tests 78 * `/test/data` - Test data 79 * `/test/mocks` - Mock files for testing 80 * `/web/app` - CSS/JS source files 81 * `/web/static` - Compiled static public assets 82 * `/web/templates` - View templates 83 84 ## Development 85 86 ### Back-end 87 88 The back-end can be extended and modified following the folder structure above. 89 Tests for each file live alongside and are designed to be easy to read and as 90 functionally complete as possible. 91 92 The easiest way to develop incrementally is to use a local go installation and 93 run your Journal as follows: 94 95 ```bash 96 go run journal.go 97 ``` 98 99 Naturally, any changes to the logic or functionality will require a restart of 100 the binary itself. 101 102 #### Dependencies 103 104 The application currently only has one dependency: 105 106 * [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3) 107 108 This can be installed using the following commands from the journal folder: 109 110 ```bash 111 go get -v ./... 112 go install -v ./... 113 ``` 114 115 #### Templates 116 117 The templates are in `html/template` format in _web/templates_ and are used 118 within each of the controllers. These can be modified while the binary stays 119 loaded, as they are loaded on the fly by the application as it runs and serves 120 content. 121 122 ### Front-end 123 124 The front-end source files are in _web/app_ and require some tooling and 125 dependencies to be installed via `npm` such as gulp and webpack. You can then 126 use the following build targets: 127 128 * `gulp sass` - Compiles the SASS source into CSS 129 * `gulp webpack` - Uglifies and minifies the JS 130 * `gulp` - Watches for changes in SASS/JS files and immediately compiles 131 132 ### Building/Testing 133 134 All pushed code is currently built using GitHub Actions to test PRs, build 135 packages and create releases. 136 137 To test locally, simply use: 138 139 ```bash 140 go test -v ./... 141 ``` 142 143 ### Building for Lambda 144 145 The application is designed to run as a Lambda connected to an EFS for SQLite 146 storage. This requires a different method of building to ensure it includes the 147 appropriate libraries and is built for the correct architecture. 148 149 To build for Lambda, you will need the x86_64-unknown-linux-gnu cross compiler 150 (if you're on a Mac): 151 152 ```bash 153 brew tap SergioBenitez/osxct 154 brew install x86_64-unknown-linux-gnu 155 ``` 156 157 To build, simply run: 158 159 ```bash 160 make build 161 ``` 162 163 This will produce a Lambda output: `lambda.zip`, that you can upload onto an 164 Amazon Linux 2023 (al2023) runtime Lambda, if you configure the appropriate 165 environment variables.