This document assumes that you are a some what experienced developer and that you are familiar with Go projects and software development.
This is developed and tested on Linux and FreeBSD. It should work just fine on any Unix like OS. We have no clue if it works on Windows, so if that's your jam, let us know how it works.
Since links depends on a few projects we also maintain we find it useful to use
a go.work file so we can make changes and test directly in links. This is
completely optional. This example go.work file assumes (obviously) that the
repos listed are cloned in the links repo parent directory.
go 1.20
use (
.
../carrier
../carrier/ses
../carrier/smtp
../gobwebs
../migrate
../gobwebs-ses-feedback
../gobwebs-formguard
../gobwebs-oauth2
../sendygo
)
We suggest using air for hot reloading upon file changes. This is totally
optional and you can use whatever you'd like to manage changes and rebuilding.
If you'd like to use air, this is an example .air.toml file:
root = "/home/pjs/development"
testdata_dir = "links/testdata"
tmp_dir = "links/tmp"
[build]
bin = "./links"
cmd = "rm -f ./links && make links"
delay = 1000
exclude_dir = ["links/assets", "links/tmp", "links/vendor", "links/testdata", "links/media", "links/api"]
exclude_file = []
exclude_regex = ["_test.go"]
exclude_unchanged = false
follow_symlink = false
full_bin = ""
include_dir = ["links", "carrier", "gobwebs", "gobwebs-oauth2"]
include_ext = ["go", "tpl", "tmpl", "html"]
kill_delay = "0s"
log = "build-errors.log"
send_interrupt = false
stop_on_error = true
[color]
app = ""
build = "yellow"
main = "magenta"
runner = "green"
watcher = "cyan"
[log]
time = false
[misc]
clean_on_exit = false
[screen]
clear_on_rebuild = false
This will only run the main service links. You still need to run the
api, shorts or list services apart in another terminal.
To get your local environment setup you should follow the steps in the build documentation.
Each service (links, short, list) uses the concept of domains (or hosts) bound
to each one. A service can have the "system" (default) domain or a custom user
domain. Because of this, you need to setup custom domains in your development
environment. You can do this by editing your /etc/hosts file and add fake
domains. Something like:
127.0.0.1 links.dev, shorts.dev, lists.dev, api.dev
The domains used should be reflected in the config.ini file as well. During
setup the script will also ask for domains for each service (except api) and
you should enter the matching domain.
If you want to use localhost for each domain, this is possible but you will
need to remove a database constraint first. After you've run the ./links migrate
command you will need to do the following in a database shell to be able to
use the same domain for multiple services. So do the following:
$ psql links yourusername
psql (16.3)
Type "help" for help.
links=> BEGIN;
BEGIN
links=*> ALTER TABLE domains DROP CONSTRAINT unique_lookup_name_active;
ALTER TABLE
links=*> COMMIT;
Now when running ./links-admin setup you can enter the same domain (ie,
localhost) for each service.
We use an email workflow to contribute your work to the project.
We accept patches submitted via git send-email. If you're not familiar with
this, don't be worried. It's very easy and you should be ready to contribute in
a couple of minutes. Start with this website:
git-send-email.io
The mailing list where you submit your patches is
~netlandish/links-dev@lists.code.netlandish.com. You can also view the
archives on the web here:
https://lists.code.netlandish.com/~netlandish/links-dev
To quickly setup your clone of links to submit to the mailing
list run the following commands:
$ git config sendemail.to "~netlandish/links-dev@lists.code.netlandish.com"
$ git config format.subjectPrefix "PATCH links"
We have more information on the topic here:
commit 2aac1348afc29af64b6d24324bd435bffb2881d1 Author: Peter Sanchez <peter@netlandish.com> Date: 2025-02-24T14:03:34-06:00 Fixing anchor name in support doc