143 lines
5.0 KiB
Markdown
143 lines
5.0 KiB
Markdown
# nonshy website
|
|
|
|
This is the source code to the main [nonshy.com](https://www.nonshy.com/)
|
|
website. It is written in Go and released under the GNU General Public
|
|
License.
|
|
|
|
This website is open source and if you'd like to help work on it (fix bugs
|
|
or contribute new features), you may sign up an account on the
|
|
[code.nonshy.com](https://code.nonshy.com/) server. See the
|
|
[CONTRIBUTING.md](CONTRIBUTING.md) file for details.
|
|
|
|
## Dependencies
|
|
|
|
You may need to run the following services along with this app:
|
|
|
|
* A **Redis cache** server: [redis.io](https://redis.io)
|
|
* (Optional) a **PostgreSQL database:** [postgresql.org](https://www.postgresql.org/)
|
|
|
|
The website can also run out of a local SQLite database which is convenient
|
|
for local development. The production server runs on PostgreSQL and the
|
|
web app is primarily designed for that.
|
|
|
|
### PostGIS Extension for PostgreSQL
|
|
|
|
For the "Who's Nearby" feature to work you will need a PostgreSQL
|
|
database with the PostGIS geospatial extension installed. Usually
|
|
it might be a matter of `dnf install postgis` and activating the
|
|
extension on your nonshy database as your superuser (postgres):
|
|
|
|
```psql
|
|
create extension postgis;
|
|
```
|
|
|
|
If you get errors like "Type geography not found" from Postgres when
|
|
running distance based searches, this is the likely culprit.
|
|
|
|
## Building the App
|
|
|
|
This app is written in Go: [go.dev](https://go.dev). You can probably
|
|
get it from your package manager, e.g.
|
|
|
|
* macOS: `brew install golang` with homebrew: [brew.sh](https://brew.sh)
|
|
* Linux: it's in your package manager, e.g. `apt install golang`
|
|
|
|
Use the Makefile (with GNU `make` or similar):
|
|
|
|
* `make setup`: install Go dependencies
|
|
* `make build`: builds the program to ./nonshy
|
|
* `make run`: run the app from Go sources in debug mode
|
|
|
|
Or read the Makefile to see what the underlying `go` commands are,
|
|
e.g. `go run cmd/nonshy/main.go web`
|
|
|
|
## Configuring
|
|
|
|
On first run it will generate a `settings.json` file in the current
|
|
working directory (which is intended to be the root of the git clone,
|
|
with the ./web folder). Edit it to configure mail settings or choose
|
|
a database.
|
|
|
|
For simple local development, just set `"UseSQLite": true` and the
|
|
app will run with a SQLite database.
|
|
|
|
## Usage
|
|
|
|
The `nonshy` binary has sub-commands to either run the web server
|
|
or perform maintenance tasks such as creating admin user accounts.
|
|
|
|
Run `nonshy --help` for its documentation.
|
|
|
|
Run `nonshy web` to start the web server.
|
|
|
|
```bash
|
|
nonshy web --host 0.0.0.0 --port 8080 --debug
|
|
```
|
|
|
|
## Create Admin User Accounts
|
|
|
|
Use the `nonshy user add` command like so:
|
|
|
|
```bash
|
|
$ nonshy user add --admin \
|
|
--email name@domain.com \
|
|
--password secret \
|
|
--username admin
|
|
```
|
|
|
|
Shorthand options `-e`, `-p` and `-u` can work in place of the longer
|
|
options `--email`, `--password` and `--username` respectively.
|
|
|
|
After the first admin user is created, you may promote other users thru
|
|
the web app by using the admin controls on their profile page.
|
|
|
|
## A Brief Tour of the Code
|
|
|
|
* `cmd/nonshy/main.go`: the entry point for the Go program.
|
|
* `pkg/webserver.go`: the entry point for the web server.
|
|
* `pkg/config`: mostly hard-coded configuration values - all of the page
|
|
sizes and business logic controls are in here, set at compile time. For
|
|
ease of local development you may want to toggle SkipEmailValidation in
|
|
here - the signup form will then directly allow full signup with a user
|
|
and password.
|
|
* `pkg/controller`: the various web endpoint controllers are here,
|
|
categorized into subpackages (account, forum, inbox, photo, etc.)
|
|
* `pkg/log`: the logging to terminal functions.
|
|
* `pkg/mail`: functions for delivering HTML email messages.
|
|
* `pkg/markdown`: functions to render GitHub Flavored Markdown.
|
|
* `pkg/middleware`: HTTP middleware functions, for things such as:
|
|
* Session cookies
|
|
* Authentication (LoginRequired, AdminRequired)
|
|
* CSRF protection
|
|
* Logging HTTP requests
|
|
* Panic recovery for unhandled server errors
|
|
* `pkg/models`: the SQL database models and query functions are here.
|
|
* `pkg/models/deletion`: the code to fully scrub wipe data for
|
|
user deletion (GDPR/CCPA compliance).
|
|
* `pkg/photo`: photo management functions: handle uploads, scale and
|
|
crop, generate URLs and deletion.
|
|
* `pkg/ratelimit`: rate limiter for login attempts etc.
|
|
* `pkg/redis`: Redis cache functions - get/set JSON values for things like
|
|
session cookie storage and temporary rate limits.
|
|
* `pkg/router`: the HTTP route URLs for the controllers are here.
|
|
* `pkg/session`: functions to read/write the user's session cookie
|
|
(log in/out, get current user, flash messages)
|
|
* `pkg/templates`: functions to handle HTTP responses - render HTML
|
|
templates, issue redirects, error pages, ...
|
|
* `pkg/utility`: miscellaneous useful functions for the app.
|
|
|
|
## Cron workers
|
|
|
|
You can schedule the `nonshy vacuum` command in your crontab. This command
|
|
will check and clean up the database for things such as: orphaned comment
|
|
photos (where somebody uploaded a photo to post on the forum, but then didn't
|
|
finish creating their post).
|
|
|
|
```cron
|
|
0 2 * * * cd /home/nonshy/git/website && ./nonshy vacuum
|
|
```
|
|
|
|
## License
|
|
|
|
GPLv3.
|