README
¶
Selfster
A Self-hosted wishlist and gift-exchange app built in Go.
We like using wishlists and exchange applications for gifting events like holidays, birthdays, weddings, house-warmings, etc. They are a convenient way to express the things that you are interested in and helps your family and friends pick a gift that will be really appreciated. However, the most convenient webapps for wishlists and gift-exchanges are not very privacy focused and make money off of spying on what you put in your list and what you buy through affiliate links. On top of that they don't have a very stable or clear UI for their exchanges. We aim to create a much more robust, documented, minimal and privacy focused alternative to other wishlist applications.
Development
Mage
Tasks are automated using Mage. Mage is included as a project dependency as some of the target implementations use mage library functions. However, to run the mage executable, it is recommended that you follow the installation instructions found in the mage project README.md.
tl;dr:
git clone https://github.com/magefile/mage
cd mage
go run bootstrap.go
cd ~/path/to/selfster
mage -l
The dev target will install development tools for the project into your development environment, beyond the direct dependencies of the application itself, such as linters, sqlc etc.
mage -v dev
In order to log in to the system, you will need to preload the database with an initial profile. You can do this by running the initDB magefile target and providing an email address. When using MailHog without additional arguments or config, sent emails will be intercepted regardless of the email address an printed to stdout, so the actual email address you choose for dev purposes is arbitrary.
mage -v initDB example@email.com
Now you can run MailHog and the run magefile target to up your local development environment.
MailHog &
mage -v run &
Configuration
Most configuration is provided by environment variable rather than by CLI flag. Currently supported environment variables are documented on the wiki.
For example, to change the listening port, set LISTEN_ADDR and BASE_URL
$ env LISTEN_ADDR=127.0.0.1:8888 BASE_URL=http://localhost:8888 mage -v run
Running target: Run
exec: git "describe" "--always" "--match=v*" "--tags" "--dirty"
go run -ldflags "-X git.sysreturn.net/auxreturn/selfster/version.Version=009c92e" git.sysreturn.net/auxreturn/selfster -debug
exec: go "run" "-ldflags" "-X git.sysreturn.net/auxreturn/selfster/version.Version=009c92e" "git.sysreturn.net/auxreturn/selfster" "-debug"
time=1970-01-01T00:00:00.001-00:00 level=DEBUG msg="Debug logging enabled"
time=1970-01-01T00:00:00.001-00:00 level=INFO msg="Reading configuration"
time=1970-01-01T00:00:00.002-00:00 level=INFO msg="current schema" version=5
time=1970-01-01T00:00:00.003-00:00 level=INFO msg="want schema" version=5
time=1970-01-01T00:00:00.003-00:00 level=INFO msg="Spawning services"
time=1970-01-01T00:00:00.009-00:00 level=INFO msg="HTTP Server listening" addr=127.0.0.1:8888 tls=false
Linting
Before submitting patches, be sure to clear any issues in linters and formatters. Here we use the golangci-lint suite to do static analysis. To run locally, start by installing into your development environment, then all you have to do is run it to flag any errors from the configured checks.
$ go fmt ./...
$ golangci-lint run
Database Interfaces
DB Models and Queries are exposed to the application through the
database.Querier Struct. This is generated through the sqlc tool.
mage generate
Sqlite
One caveat of using the sqlite3 database engine is that the C stdlib must be present on the target deployment platform and the compiling environment must have a C compiler toolchain to build the binary. On linux environments, you're usually good with the standard toolchain plus the sqlite3 development package.
# Debian/Ubuntu
sudo apt-get install sqlite3-dev
# Fedora
sudo dnf install sqlite-devel
The main login method into to the ui of the app is authenticated using an email link mechanism. So that means to be able to login you must be able to send and receive emails to retreive the link. You can add the smtp credentails of your favored mail service to your local config, or you can run a local smtp server to catch the email. Mailhog is a convenient tool you can run to recieve email locally. It works out of the box with selfster.
mage -v run &
MailHog &
Login email will be printed to stdout where you can paste to your browser to authenticate your development session.
By default, without an smtp user set, emails are not sent and a login link is printed to the screen when a valid email is entered, allowing easy development authentication.
Windows Builds
See this windows with sqlite build script to get started
Documentation
¶
Overview ¶
Selfster is a self-hosted wishlist registry and gift exchange application.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth provides authentication and authorization routines like login and session handling.
|
Package auth provides authentication and authorization routines like login and session handling. |
|
Package cli handles command line parsing and application initialization.
|
Package cli handles command line parsing and application initialization. |
|
Package config implements parsing and setting app configuration options
|
Package config implements parsing and setting app configuration options |
|
Package crypto provides cryptographic actions and primitives.
|
Package crypto provides cryptographic actions and primitives. |
|
Package database provides low-level database connections and querier adapters for the application
|
Package database provides low-level database connections and querier adapters for the application |
|
Package email implements adapters for sending messages over smtp
|
Package email implements adapters for sending messages over smtp |
|
http
|
|
|
request
Package request provides helpers and access methods for working with http requests
|
Package request provides helpers and access methods for working with http requests |
|
request/binding
Package binding provides functions for binding input to internal parameter structures and verifying those bindings.
|
Package binding provides functions for binding input to internal parameter structures and verifying those bindings. |
|
response
Package response formats and writes http responses
|
Package response formats and writes http responses |
|
response/html
Package html provides a high level builder interface for html responses
|
Package html provides a high level builder interface for html responses |
|
response/json
Package json formats JSON http responses
|
Package json formats JSON http responses |
|
route
Package route helps build paths from named routes
|
Package route helps build paths from named routes |
|
Package log provides logging functions and middleware
|
Package log provides logging functions and middleware |
|
Mage is a make-like build tool implemented in Go
|
Mage is a make-like build tool implemented in Go |
|
Package profiles provides access to user profiles and their associated methods
|
Package profiles provides access to user profiles and their associated methods |
|
service
|
|
|
httpd
Package httpd contains helpers from running an http deamon
|
Package httpd contains helpers from running an http deamon |
|
Package ui defines the routes and templates for the HTML user interface.
|
Package ui defines the routes and templates for the HTML user interface. |
|
static
Package static handles processing and retreiving static assets.
|
Package static handles processing and retreiving static assets. |
|
template
Package template provides a templating engine for presenting the ui.
|
Package template provides a templating engine for presenting the ui. |
|
Package version holds application and build information
|
Package version holds application and build information |
|
Package wishlists contains actions related to wishlists
|
Package wishlists contains actions related to wishlists |