Portainer Templates logo

Portainer Templates

GoCostWeb

Stack

Personal Finance

Golang-based web application for personal expense management, focused on a clean monthly workflow and intuitive tracking of recurring and non-recurring costs.

Source details

Repo: madalinpopa/gocost-web
Stars: 70
Forks: 6
Language: Go
License: MIT
Latest: v1.8.4 · 6 months ago
Updated: 5 months ago
Website: cost.coderustle.ro/

Configuration

Type
Compose
Platform
linux
Image
ghcr.io/madalinpopa/gocost-web:${VERSION:-latest}
Ports
4000:4000
Env vars
ALLOWED_HOSTS=${ALLOWED_HOSTS:-localhost}DOMAIN=${DOMAIN:-localhost}CURRENCY=${CURRENCY:-USD}DB_PATH=/app/data/data.sqlite
Source
Repo

Template by xneo1·Source

Standalone Install

Select an install method, to see config/commands for deploying GoCostWeb

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select GoCostWeb, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo
Original stackfile

The compose file this template deploys, straight from its repo:

services:
  gocost:
    image: ghcr.io/madalinpopa/gocost-web:${VERSION:-latest}
    ports:
      - "4000:4000"
    environment:
      ALLOWED_HOSTS: ${ALLOWED_HOSTS:-localhost}
      DOMAIN: ${DOMAIN:-localhost}
      CURRENCY: ${CURRENCY:-USD}
      DB_PATH: /app/data/data.sqlite
    volumes:
      - type: volume
        source: gocost_data
        target: /app/data
      - type: volume
        source: gocost_uploads
        target: /app/uploads
    networks:
      - public
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--quiet",
          "--tries=1",
          "--spider",
          "http://localhost:4000/",
        ]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  public:
    external: true

volumes:
  gocost_data:
  gocost_uploads:

Or deploy it directly from the source:

git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/gocostweb.yml up -d

More install options in our documentation, or see madalinpopa/gocost-web for app-specific guidance.

gocost-web

GitHub go.mod Go version
Golang-based web application for personal expense management, focused on a clean monthly workflow and intuitive tracking of recurring and non-recurring costs.
Live demo: cost.coderustle.ro User: admin@gocost.ro, Password: secret123

Screenshots

Dashboard

Overview

Typical Workflow

  • Pick a month: Move between months to review past spending or plan upcoming costs.
  • Create Groups: Create groups (e.g., Housing, Transportation) to organize your expenses.
  • Set up Categories: Inside each group, create categories (e.g., Rent, Groceries). Define a budget for the category and choose if it is recurrent or for the current month only.
  • Record Expenses: Add specific expenses to a category (e.g., "Weekly Shop"). Mark them as paid or unpaid to track cash flow.
  • Review Status: Visually track spending against your category budgets and see what's left to pay.

Core Features

  • Category Management: Organize expenses into groups (e.g., Housing, Transportation).
  • Flexible Category Types:
- **This month only**: applies only to the currently selected month.
- **Recurrent**: persists across months until a specified end date (or indefinitely).

Recording Expenses

For each expense category, the user can record expenses by providing:
  • an amount, and
  • a payment status (paid or unpaid).

The payment status is visually reflected in the category so the user can immediately see which expenses are settled and which are pending.

User Experience Goals

  • Intuitive navigation centered on monthly context.
  • Clear grouping of categories and expenses.
  • Efficient handling of both recurring and non-recurring costs.

Technical Details

  • Backend: Go (1.26.1+), net/http, a-h/templ for server-side UI rendering.
  • Frontend: Tailwind CSS, HTMX for server-driven updates, Alpine.js for lightweight client state.
  • Data: SQLite database with migrations managed by goose.
  • Configuration: Environment-driven configuration via .envrc (generated from envrc.template).
  • Tooling: make targets for build/dev/test; air for live reload.

Environment Variables

Required:
  • ALLOWED_HOSTS: comma-separated list of allowed hostnames (e.g. localhost,example.com).
  • DOMAIN: base domain for the app (e.g. localhost or gocost.example).

Optional:
  • CURRENCY: ISO 4217 currency code (default: USD).
  • TRUSTED_PROXIES: comma-separated list of trusted proxy IP addresses or CIDR ranges.
  • APP_ENV: application environment, typically production or development (default: development).
  • APP_ADDR: the address the web server listens on (default: 0.0.0.0).
  • APP_PORT: the port the web server listens on (default: 4000).
  • DB_PATH: SQLite file path used by the Docker entrypoint (default: /app/data/data.sqlite).
  • VERSION: Docker image tag used by compose.yml (default: latest).
  • GOOSE_DRIVER, GOOSE_DBSTRING, GOOSE_MIGRATION_DIR: used by goose during development (see envrc.template).

Project Structure

  • cmd/web: web server entry point.
  • internal/domain: core business entities.
  • internal/usecase: application use cases and interfaces.
  • internal/interfaces: HTTP handlers, routing, and web adapters.
  • internal/infrastructure: configuration and storage implementations.
  • ui: Templ components and static assets.
  • migrations: SQL migration files.

Run Locally with Docker

Use the provided Dockerfile and compose.yml to build and run the app locally.

Using Docker Compose

# build the image for local use
docker build -t ghcr.io/madalinpopa/gocost-web:local .

# create the external network used by compose (safe if it already exists)
docker network create public

# start the app on http://localhost:4000
VERSION=local docker compose up

Optional environment overrides (set before docker compose up): ALLOWED_HOSTS, DOMAIN, CURRENCY.

Using Docker Run

To run the container without Docker Compose:
# build the image
docker build -t ghcr.io/madalinpopa/gocost-web:local .

# run the container
docker run -d \
  --name gocost \
  -p 4000:4000 \
  -e ALLOWED_HOSTS=localhost \
  -e DOMAIN=localhost \
  -v gocost_data:/app/data \
  ghcr.io/madalinpopa/gocost-web:local

Development

Prerequisites

  • Go 1.26.1+
  • Node.js + npm (Tailwind CLI)
  • Optional: direnv and 1Password CLI (op) for .envrc generation

Common Commands

  • make init: download deps, generate Templ, install npm packages, create .envrc.
  • make dev: run server + Templ + Tailwind watchers with live reload.
  • make build/web: build the web server binary to bin/server.
  • make test: run Go tests under ./internal....
  • make test/race: run race detector tests.
  • make check: run go vet and staticcheck.

Contributing

Contributions are welcome. Please follow these steps:
  1. Fork the repository and create a feature branch.
  2. Keep changes focused and follow the existing project layout.
  3. Run make test (and make check if you have staticcheck) before opening a PR.
  4. If you change .templ files or CSS, ensure generated files are up to date.
  5. Open a pull request with a clear description of the change.

Serve GoCostWeb on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying gocostweb.example.com to http://gocost:4000

Add this to your Caddyfile

gocostweb.example.com {
	reverse_proxy http://gocost:4000
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:4000 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :4000
  • Stop the other service, or pick a different host port. In 4000:4000 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: http://your-server-ip:4000. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, gocost can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 4000

Image won't pull

Test the pull directly on the host: docker pull ghcr.io/madalinpopa/gocost-web:${VERSION:-latest}

  • "manifest unknown" means the tag no longer exists.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

  • YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A Compose stack

GoCostWeb is a Compose stack, a set of containers defined in one file and brought up together by Portainer, then started and stopped as a single app.

The app image

An image is the app packed up ready to go, everything GoCostWeb needs bundled into one download. This template pulls ghcr.io/madalinpopa/gocost-web:latest, which Docker fetches once and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. GoCostWeb's comes from the GitHub Container Registry, published by madalinpopa.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Pin a specific tag if you would rather stay on one version.

Ports

A port is the door the app answers on. A mapping like 4000:4000 means it's reachable on port 4000 of your server, where the left number is yours to change and the right one belongs to the app. It opens:

  • 4000:4000

No stored data

This template doesn't mount any storage, so whatever GoCostWeb writes stays inside the container and is wiped if it's recreated or updated. That's fine for something stateless, but add a volume before trusting it with anything you want to keep.

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. GoCostWeb takes 4 of them, all with defaults you can leave alone or tweak:

  • ALLOWED_HOSTS, defaults to localhost
  • DOMAIN, defaults to localhost
  • CURRENCY, defaults to USD
  • DB_PATH, defaults to /app/data/data.sqlite

Health check

A health check is how Docker tells whether GoCostWeb is really working, not just switched on. It runs wget --quiet --tries=1 --spider http://localhost:4000/ every 30s and flags the container as unhealthy if that keeps failing.

Networking

Nothing custom is set, so GoCostWeb sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container gocost. That's what you'll spot in the containers list and use in commands like docker logs gocost.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

GoCostWeb is open source, released under the MIT license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set GoCostWeb up. Add the template list to Portainer once, then deploying GoCostWeb is a click rather than a wall of config.