conorganizer

Con Organizer

Table of Contents

1. Description
2. Quick Start
   • Docker Setup
   • Direct Installation
3. Database Issues: events.db Troubleshooting
4. IDE Setup
   • NeoVim Configuration
5. Troubleshooting
6. Linux/Mac Setup Guide
   • Prerequisites
   • Verification and Startup
7. Migrations
   • Running Goose manually
   • Pushing migrations to prod
   • Step by step
8. Agent Skills Path Compatibility
9. Update go dependencies
10. Additional Resources

Description

This is a spike exploring Go, Datastar and Templ using the Northstar template.

For more details, visit:

• Templ Documentation
• Data-Star Documentation

Quick Start

Choose your preferred method to run the project:

Docker Setup (Recommended for Windows)

1. Start the application using Docker Compose

docker compose up --build

1. Once the containers are up and running, head over to Access the Application to view the app in your browser.

[!NOTE] Docker is a platform that allows you to run applications in containers. It handles all dependencies and environment configuration automatically, making it ideal for Windows users.

Direct Installation

Follow the Linux/Mac Setup Guide below.

Database Issues: events.db Troubleshooting

[!NOTE] To get the latest backup of the database and all the images from prod run: The database download requires DB_SSH_USER in your .env file or shell environment. The database task creates a temporary SQLite backup snapshot on the server; it does not copy the live WAL-mode database file directly.

go tool task download

Production SQLite operational notes are in documentation/sqlite-production.md.

To get the latest schema of the database, run:

sqlite3 database/events.db ".schema --indent" > schema.sql

[!TIP] Format the schema.sql using the prettier plugin in your IDE to make it look nice.

IDE Setup

See Templ Guide: Developer Tools for detailed IDE support information.

NeoVim Configuration

Templ Support

[!WARNING] Do not install joerdav/templ.vim - it is deprecated.

SQL Support with Dadbod

Add these plugins to your NeoVim configuration:

{
  "tpope/vim-dadbod",
  "kristijanhusak/vim-dadbod-completion",
  {
    "kristijanhusak/vim-dadbod-ui",
    config = function()
      vim.keymap.set("n", "<leader>td", ":DBUIToggle<CR>", { desc = "Toggle Dadbod UI" })
    end,
  },
}

Helpful Dadbod tutorials:

• Basic Setup and Usage
• Advanced Features

Troubleshooting

Common issues and solutions:

• Manual generate templ: If you encounter issues with Templ, run:

templ generate && go build -buildvcs=false -o tmp/main .

• Tool not found: Ensure $HOME/go/bin is in your PATH
• Port in use: Check if another service is using port 7331 or 8080
• Database errors: See Database Issues
• Build errors: Run go mod tidy to fix dependencies

Linux/Mac Setup Guide

[!NOTE] Windows users should use Docker Setup for consistency.

Prerequisites

1. Required Tools

2. Shell Configuration

# Add to ~/.bashrc (Linux) or ~/.bash_profile (macOS)
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.bashrc  # or ~/.bash_profile for macOS

# Apply changes
source ~/.bashrc  # or source ~/.bash_profile for macOS

# Add Go binaries to PATH
echo 'export PATH=$PATH:$HOME/go/bin' >> ~/.zshrc

# Apply changes
source ~/.zshrc

Update templ

go install github.com/a-h/templ/cmd/templ@latest

Verification and Startup

1. Verify Tool Installation:

   Check Go installation:

   go version
   

   Check Templ installation:

   templ version
   

   Check Air installation:

   air -v
   

   Check Task installation:

   go tool task --version
   

[!TIP] Each command should return a version number. If any command fails:

1. Ensure the tool is installed correctly
2. Verify your PATH includes Go binaries
3. Try reopening your terminal

1. Start Development Server:

   go tool task start
   

[!NOTE] This will start the server with hot-reload enabled. Any code changes will automatically trigger a rebuild.

Access the Application:

http://localhost:7331

Migrations with goose

[!NOTE] Goose will try to read some basic variables from .env, make sure that this file is updated with the most recent version from discord before running any commands.

We're using Goose in our migration process for its simplicity and reliability. While Goose is available as a go dependency for programmatically migrating databases, we're mostly using its CLI tool for manual updates.

Running Goose manually

[!WARNING] Before running Goose, run go tool task download to fetch the newest version of the database! You can install Goose CLI tool from here, afterwards you should have goose globally available in your terminal. Migrations are manual only. Do not add automatic migrations to application startup, health checks, readiness checks, or systemd startup.

To create a new migration file you can run the following command, read here for more annotation examples.

goose create <briefly describe changes> sql

After you've added your migration files you can use the keywords up or down to handle the migrations

goose up

Pushing migrations to prod and services

[!CAUTION] Make sure that you can do all of the following steps before you start. These actions require goose, account on server.

1. Run goose on local db (preferably a copy)
2. make a backup on server
3. upload to server.
4. profit

Step By Step To Update DB

1. Find The Correct Service Name

systemctl list-units --type=service | grep -i conorganizer
systemctl list-unit-files | grep -i conorganizer

2. Inspect The Service

Set the service name:

SERVICE=conorganizer-{service-name}.service

Check the service command and find the mounted database path:

systemctl show "$SERVICE" -p ExecStart --value | fold -s -w 120

Look for the host path that contains events.db or maps the database folder into the app.

Example:

/mnt/HC_Volume_103911252/environments/1337-merge/database:/app/database

In that case the database path is:

/mnt/HC_Volume_103911252/environments/1337-merge/database/events.db

3. Replace The Database

Set the paths:

DB_PATH="{mounted path to db}/events.db"
UPLOADED_DB="/home/{account-name}/events.db"

Stop the service:

sudo systemctl stop "$SERVICE"

Back up the current database:

sudo cp -a "$DB_PATH" "$DB_PATH.bak.$(date +%Y%m%d-%H%M%S)"

Move the uploaded database into place:

sudo mv "$UPLOADED_DB" "$DB_PATH"

Fix ownership and permissions:

sudo chown deploy:deploy "$DB_PATH"
sudo chmod 644 "$DB_PATH"

Start the service again:

sudo systemctl start "$SERVICE"
sudo systemctl status "$SERVICE"

Check logs:

journalctl -u "$SERVICE" -n 100 --no-pager

Agent Skills Path Compatibility

Some agents do not discover skills directly from .agents/skills.

If that happens, link each skill into that agent's own skills folder (create the folder first if needed).

If you need a true symlink instead (may require admin/dev mode):

$agentSkillsFolder = ".codex\skills"  # replace with your agent's skills folder
New-Item -ItemType Directory -Force -Path $agentSkillsFolder | Out-Null
New-Item -ItemType SymbolicLink -Path "$agentSkillsFolder" -Target ".agents\skills"

Update Dependencies

Update all Go dependencies:

go get -u
go mod tidy

Check what changed:

git diff go.mod go.sum

Verify tool versions used by the repo:

go tool templ version
go tool task --version
go tool air -v

If templ was updated, make sure workflow pins match the new version where relevant, especially:

.github/workflows/golangci-lint.yml

Look for hardcoded commands like:

go install github.com/a-h/templ/cmd/templ@v0.3.1020

and update the version to match go.mod.

Additional Resources

• Northstar Template Documentation
• Go Documentation
• Docker Documentation