Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,9 @@ config.*
*secret*
*token*

# Compose and local IDP configuration
# Compose and local configuration
docker-compose*.yaml
docker-compose*.yml
local-idp.*

# Runtime databases and application data
data/
Expand All @@ -36,9 +35,6 @@ bin/
build/
dist/
coverage/
node_modules/
test-results/
playwright-report/
*.exe
*.dll
*.so
Expand Down
22 changes: 7 additions & 15 deletions .env.example
Original file line number Diff line number Diff line change
@@ -1,29 +1,21 @@
# Copy this file to .env and replace the required values.
# Non-empty STICK_* values override values from earlier configuration providers.
# The callback URL for the OIDC client is <public-url>/auth/callback.
# The API is available below <public-url>/api/v1.

# Required application settings. A filesystem path selects SQLite;
# postgres://, postgresql://, mongodb://, or mongodb+srv:// selects the
# corresponding database backend. MongoDB must use a replica set or mongos.
STICK_DATABASE=/data/stick.db
# Public URL used for links and OIDC redirects. HTTPS is required except for
# loopback addresses used during local development. Include the mount path, if any.
# Optional public URL used for notification links and the application mount path.
# Defaults to http://localhost. HTTPS is required for non-local URLs.
STICK_SERVER_PUBLIC_URL=http://localhost:8080
# Address to bind (default: :8080).
STICK_SERVER_LISTEN_ADDR=:8080

# OIDC provider settings. Any compliant provider can be used.
STICK_AUTH_OIDC_ISSUER=https://accounts.google.com
STICK_AUTH_OIDC_CLIENT_ID=your-client-id
STICK_AUTH_OIDC_CLIENT_SECRET=your-client-secret
# Use at least 32 random bytes; generate one with: openssl rand -hex 32
STICK_AUTH_SESSION_SECRET=replace-with-at-least-32-random-bytes

# Optional settings for the local Keycloak instance in compose.idp.yaml.
# Set IDP_ADMIN_PASSWORD before starting that Compose override.
# STICK_IDP_PUBLIC_URL=http://localhost:8081/idp
# IDP_ADMIN_USERNAME=admin
# IDP_ADMIN_PASSWORD=replace-with-a-random-password
# External JWT validation settings.
STICK_AUTH_IDP_ENDPOINT=https://accounts.google.com
STICK_AUTH_AUDIENCE=your-api-audience
STICK_AUTH_SCOPE=your-required-scope

# Optional comma-separated administrator list.
# STICK_AUTH_ADMIN_EMAILS=alice@example.com,bob@example.com
Expand Down
18 changes: 1 addition & 17 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -70,25 +70,9 @@ jobs:
vuln-type: os,library
severity: CRITICAL,HIGH

browser:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-go@v6
with:
go-version-file: go.mod
cache: true
- uses: actions/setup-node@v5
with:
node-version: 24
cache: npm
- run: npm ci
- run: npx playwright install --with-deps --only-shell chromium
- run: npm run test:browser

publish-image:
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/'))
needs: [test, race, lint, analysis, image, browser]
needs: [test, race, lint, analysis, image]
runs-on: ubuntu-latest
permissions:
contents: read
Expand Down
2 changes: 0 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -35,5 +35,3 @@ data/
config.yaml
.env
/stickd
node_modules/
test-results/
5 changes: 1 addition & 4 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ BUILD_DATE ?= unknown
LDFLAGS := -s -w -X main.commit=$(COMMIT) -X main.buildDate=$(BUILD_DATE)
GO_FILES := $(shell find . -type d \( -name .git -o -name data -o -name node_modules -o -name vendor \) -prune -o -type f -name '*.go' -print)

.PHONY: build fmt verify-format test test-integration test-e2e test-race vet lint govulncheck image check run clean
.PHONY: build fmt verify-format test test-integration test-race vet lint govulncheck image check run clean

build:
$(GOENV) CGO_ENABLED=0 go build -trimpath -ldflags "$(LDFLAGS)" -o $(BINARY) ./cmd/stickd
Expand All @@ -29,9 +29,6 @@ test:
test-integration:
$(GOENV) CGO_ENABLED=0 go test -count=1 ./test/integration

test-e2e:
$(GOENV) CGO_ENABLED=0 go test -count=1 ./test/e2e

test-race:
$(GOENV) go test -race $(TEST_FLAGS) ./...

Expand Down
31 changes: 16 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

Stick is a small, self-hosted coordination service for shared operational resources. Users claim a stick with a reason, release it when finished, and can subscribe to release notifications.

- Uses OIDC for login.
- Provides a JSON REST API with bearer-token authentication and optimistic
concurrency using ETags.
- Supports different storage backends:
- SQLite (default)
- PostgreSQL
Expand All @@ -29,24 +30,23 @@ Copy the example environment file:
cp .env.example .env
```

Edit `.env` and set the OIDC values, a random session secret, and the public URL. HTTPS is required for non-local deployments.

Register `<public-url>/auth/callback` as the OIDC client's redirect URI.
Edit `.env` and set the identity-provider endpoint and expected audience and
scope. The public URL is optional; HTTPS is required for non-local URLs.

```sh
openssl rand -hex 32 # use the result for STICK_AUTH_SESSION_SECRET
docker compose up -d --build
```

Stick is available at `STICK_SERVER_PUBLIC_URL`. The Compose file binds it to loopback, so put it behind a TLS reverse proxy for remote access.
The API is available at `STICK_SERVER_PUBLIC_URL/api/v1`. The Compose file
binds it to loopback, so put it behind a TLS reverse proxy for remote access.

### Kubernetes

Create and edit the application configuration. Keep this file private because it contains credentials:

```sh
cp example.config.yaml config.yaml
# edit config.yaml and set a random session_secret
# edit config.yaml and set the API authentication values
kubectl create namespace stick
kubectl -n stick create secret generic stick-config --from-file=config.yaml=./config.yaml
```
Expand All @@ -59,7 +59,8 @@ kubectl apply -f example.kubernetes.yaml

This creates a single-replica Deployment, Service, and persistent volume claim.

Expose the Service through an Ingress or Gateway, use its HTTPS URL as `STICK_SERVER_PUBLIC_URL`, and register `<public-url>/auth/callback` with the OIDC provider.
Expose the Service through an Ingress or Gateway, and use its HTTPS URL as
`STICK_SERVER_PUBLIC_URL`.

If the application is mounted under a path, include that path in the probe URLs as well.

Expand Down Expand Up @@ -104,7 +105,7 @@ When Azure is the only structured source, omit `-config`; when combining it
with a file, use `STICK_CONFIG_PROVIDERS=yaml,azure-app-config,environment`.

Use slash-separated keys such as `stick/database`,
`stick/server/public_url`, and `stick/auth/oidc/issuer`. Notification lists
`stick/server/public_url`, and `stick/auth/idp_endpoint`. Notification lists
should be stored as JSON values with the `application/json` content type.
The hierarchy separator is configurable (supported values include `/`, `.`,
`:` and `__`) and defaults to `/`.
Expand All @@ -130,10 +131,10 @@ make check
make image
```

The `compose.idp.yaml` override also starts Keycloak for local OIDC development.

Set `IDP_ADMIN_PASSWORD` in `.env`, configure Keycloak as your OIDC provider, and run it with:
Send an external JWT in the `Authorization: Bearer <token>` header. Resource
updates require the current `If-Match` ETag; reads return an ETag and support
`If-None-Match`.

```sh
docker compose -f compose.yaml -f compose.idp.yaml up -d --build
```
The API provides stick listing, creation, rename, archive/unarchive, claim,
release, history, and notification subscription endpoints below
`/api/v1`.
28 changes: 14 additions & 14 deletions cmd/stickd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,12 @@ import (
"stick/internal/adapters/persistence/mongodb"
"stick/internal/adapters/persistence/postgres"
"stick/internal/adapters/persistence/sqlite"
"stick/internal/api"
"stick/internal/application"
"stick/internal/auth"
"stick/internal/config"
"stick/internal/notification"
"stick/internal/outbox"
"stick/internal/web"
)

const version = "1.0.0"
Expand Down Expand Up @@ -87,23 +89,21 @@ func mainContext(parent context.Context, args []string) (err error) {
}()
service := application.NewService(store)

webRunner, err := web.NewRunner(service, store, web.Options{
serverRunner, err := api.NewRunner(service, store, api.Options{
PublicURL: cfg.Server.PublicURL,
ListenAddr: cfg.Server.ListenAddr,
OIDC: cfg.Auth.OIDC,
SessionSecret: cfg.Auth.SessionSecret,
JWT: auth.JWTConfig{Endpoint: cfg.Auth.IDPEndpoint, Audience: cfg.Auth.Audience, Scope: cfg.Auth.Scope},
AdminEmails: cfg.Auth.AdminEmails,
Timezone: cfg.Timezone,
NotificationsEnabled: notifier != nil,
})
if err != nil {
return fmt.Errorf("web: %w", err)
return fmt.Errorf("HTTP server: %w", err)
}

components := []application.Component{webRunner}
components := []application.Component{serverRunner}
if notifier != nil {
components = append(components, outbox.NewWorker(store, notifier, outbox.WorkerOptions{
BaseURL: cfg.Server.PublicURL.String(),
BaseURL: cfg.Server.PublicURL,
Location: cfg.Timezone,
}))
}
Expand Down Expand Up @@ -172,8 +172,8 @@ func openStore(ctx context.Context, cfg config.DatabaseConfig) (backend, error)
}
}

func buildNotifier(cfg config.NotificationsConfig) (application.Notifier, error) {
var notifiers []application.Notifier
func buildNotifier(cfg config.NotificationsConfig) (notification.Notifier, error) {
var notifiers []notification.Notifier
for i, smtpConfig := range cfg.SMTP {
notifier, err := smtp.New(smtp.Config{
Host: smtpConfig.Host,
Expand All @@ -189,23 +189,23 @@ func buildNotifier(cfg config.NotificationsConfig) (application.Notifier, error)
if err != nil {
return nil, fmt.Errorf("%s notifier: %w", notificationBackendName("smtp", i), err)
}
notifiers = append(notifiers, application.Named(notificationBackendName("smtp", i), notifier))
notifiers = append(notifiers, notification.Named(notificationBackendName("smtp", i), notifier))
}
for i, webhookConfig := range cfg.Webhook {
notifier, err := webhook.New(webhook.Config{URL: webhookConfig.URL})
if err != nil {
return nil, fmt.Errorf("%s notifier: %w", notificationBackendName("webhook", i), err)
}
notifiers = append(notifiers, application.Named(notificationBackendName("webhook", i), notifier))
notifiers = append(notifiers, notification.Named(notificationBackendName("webhook", i), notifier))
}
for i, teamsConfig := range cfg.Teams {
notifier, err := teams.New(teams.Config{URL: teamsConfig.URL})
if err != nil {
return nil, fmt.Errorf("%s notifier: %w", notificationBackendName("teams", i), err)
}
notifiers = append(notifiers, application.Named(notificationBackendName("teams", i), notifier))
notifiers = append(notifiers, notification.Named(notificationBackendName("teams", i), notifier))
}
return application.Multi(notifiers...), nil
return notification.Multi(notifiers...), nil
}

func notificationBackendName(kind string, index int) string {
Expand Down
26 changes: 12 additions & 14 deletions cmd/stickd/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,17 @@ import (
"testing"
"time"

"stick/internal/application"
"stick/internal/config"
"stick/internal/notification"
)

func TestMainContextStopsOnCanceledParent(t *testing.T) {
t.Setenv("STICK_DATABASE", filepath.Join(t.TempDir(), "stick.db"))
t.Setenv("STICK_AUTH_OIDC_ISSUER", "https://accounts.google.com")
t.Setenv("STICK_AUTH_OIDC_CLIENT_ID", "client-id")
t.Setenv("STICK_AUTH_OIDC_CLIENT_SECRET", "client-secret")
t.Setenv("STICK_AUTH_IDP_ENDPOINT", "https://accounts.google.com")
t.Setenv("STICK_AUTH_AUDIENCE", "stick-api")
t.Setenv("STICK_AUTH_SCOPE", "stick:use")
t.Setenv("STICK_SERVER_PUBLIC_URL", "http://localhost:8080")
t.Setenv("STICK_SERVER_LISTEN_ADDR", "127.0.0.1:0")
t.Setenv("STICK_AUTH_SESSION_SECRET", "0123456789abcdef0123456789abcdef")

ctx, cancel := context.WithCancel(context.Background())
cancel()
Expand Down Expand Up @@ -133,12 +132,11 @@ func TestBuildConfigProvidersRejectsUnknownProvider(t *testing.T) {
func setMinimalRuntimeEnv(t *testing.T, databasePath string) {
t.Helper()
t.Setenv("STICK_DATABASE", databasePath)
t.Setenv("STICK_AUTH_OIDC_ISSUER", "https://accounts.google.com")
t.Setenv("STICK_AUTH_OIDC_CLIENT_ID", "client-id")
t.Setenv("STICK_AUTH_OIDC_CLIENT_SECRET", "client-secret")
t.Setenv("STICK_AUTH_IDP_ENDPOINT", "https://accounts.google.com")
t.Setenv("STICK_AUTH_AUDIENCE", "stick-api")
t.Setenv("STICK_AUTH_SCOPE", "stick:use")
t.Setenv("STICK_SERVER_PUBLIC_URL", "http://localhost:8080")
t.Setenv("STICK_SERVER_LISTEN_ADDR", "127.0.0.1:0")
t.Setenv("STICK_AUTH_SESSION_SECRET", "0123456789abcdef0123456789abcdef")
}

func TestBuildNotifierWithNoBackendsSucceeds(t *testing.T) {
Expand Down Expand Up @@ -169,7 +167,7 @@ func TestBuildNotifierComposesWebhook(t *testing.T) {
if err != nil {
t.Fatalf("buildNotifier: %v", err)
}
if err := notifier.Notify(context.Background(), application.Notification{StickID: "aa001"}); err != nil {
if err := notifier.Notify(context.Background(), notification.Notification{StickID: "aa001"}); err != nil {
t.Fatalf("Notify: %v", err)
}
if payload := <-received; !strings.Contains(payload, `"stick_id":"aa001"`) {
Expand All @@ -195,7 +193,7 @@ func TestBuildNotifierComposesTeams(t *testing.T) {
if err != nil {
t.Fatalf("buildNotifier: %v", err)
}
if err := notifier.Notify(context.Background(), application.Notification{StickName: "aa001"}); err != nil {
if err := notifier.Notify(context.Background(), notification.Notification{StickName: "aa001"}); err != nil {
t.Fatalf("Notify: %v", err)
}
if payload := <-received; !strings.Contains(payload, `"@type":"MessageCard"`) || !strings.Contains(payload, `"title":"aa001 is available"`) {
Expand Down Expand Up @@ -225,7 +223,7 @@ func TestBuildNotifierComposesMultipleBackends(t *testing.T) {
if err != nil {
t.Fatalf("buildNotifier: %v", err)
}
if err := notifier.Notify(context.Background(), application.Notification{}); err != nil {
if err := notifier.Notify(context.Background(), notification.Notification{}); err != nil {
t.Fatalf("Notify: %v", err)
}
select {
Expand Down Expand Up @@ -259,7 +257,7 @@ func TestBuildNotifierComposesMultipleInstancesOfOneBackend(t *testing.T) {
if err != nil {
t.Fatalf("buildNotifier: %v", err)
}
if err := notifier.Notify(context.Background(), application.Notification{}); err != nil {
if err := notifier.Notify(context.Background(), notification.Notification{}); err != nil {
t.Fatalf("Notify: %v", err)
}
for i := 0; i < 2; i++ {
Expand Down Expand Up @@ -307,7 +305,7 @@ func TestBuildNotifierAttributesRuntimeErrors(t *testing.T) {
if err != nil {
t.Fatalf("buildNotifier: %v", err)
}
err = notifier.Notify(context.Background(), application.Notification{})
err = notifier.Notify(context.Background(), notification.Notification{})
if err == nil || !strings.Contains(err.Error(), "webhook: webhook returned 502") {
t.Fatalf("runtime error = %v", err)
}
Expand Down
19 changes: 0 additions & 19 deletions compose.idp.yaml

This file was deleted.

Loading