El Contador

Bookkeeping and expense management – expenses, sales, bank transactions, and reconciliation. Run with Docker.

Install (first time)

To use from npm: the package must be published first (npm publish from the repo); then npm install el-contador works. Before publishing or to use the latest from Git: npm install github:YOUR_ORG/el-contador (replace with your repo URL).

You do not need to install PostgreSQL on the host or create a database/user manually. The first run creates everything from your .env: PostgreSQL runs in a container and creates the user and database automatically; the app then applies the schema and creates the admin user.

1. Create a project directory and add the package:

   mkdir my-books && cd my-books
   npm init -y
   npm install el-contador

2. Create .env with the credentials you want (these will be used to create the PostgreSQL user and database on first run):

   cp node_modules/el-contador/.env.example .env

   Edit .env and set at least:

   • DB_PASSWORD – password for the database (required).
   • SESSION_SECRET – long random string for session cookies.

   Optional: DB_USER (default el_contador), DB_NAME (default el_contador_finance). The first run will create this PostgreSQL user and database inside the container; no separate setup needed.

   Run npx el-contador (or docker compose ...) from the same directory that contains .env. If you see Set DB_PASSWORD in .env, create or fix .env in that directory.

3. Start the app (this starts PostgreSQL and the backend; on first run the DB and admin user are created):

   npx el-contador

   Or without the CLI:

   docker compose --project-directory node_modules/el-contador -f node_modules/el-contador/docker-compose.yml --env-file .env up -d

4. Open the admin UI at http://localhost:3080 (or the port in ADMIN_PORT). Log in with the admin user: INIT_ADMIN_EMAIL from .env (default [email protected]), and INIT_ADMIN_PASSWORD or DB_PASSWORD if not set.

Deploy on another server

On a new server (VPS, dedicated, etc.):

1. Install Node.js (v18+), npm, Docker, and Docker Compose V2 (docker compose). The CLI requires the Compose plugin; legacy docker-compose (V1) is not supported.
2. Create a directory and install the app as above (e.g. npm init -y, npm install el-contador, copy .env.example to .env, set DB_PASSWORD and SESSION_SECRET).
3. Start with npx el-contador (or the docker compose -f ... command). The app listens on ADMIN_PORT (default 3080) on the host.
4. To expose it on a subdomain or domain (e.g. admin.example.com), configure a reverse proxy (nginx, Caddy, or Apache) on that server. The package does not install or configure nginx for you; you add the proxy config yourself. See below.

Nginx reverse proxy (subdomain / domain)

The app is built to run behind a reverse proxy (trust proxy is enabled). To serve it on a subdomain (e.g. contador.example.com) with nginx:

1. Ensure the app is running and listening on a port (e.g. 3080) on the same machine.

2. Create a server block for your subdomain. Example (HTTP only):

   server {
       listen 80;
       server_name contador.example.com;
       # Allow batch expense import (e.g. 30 files × 1MB)
       client_max_body_size 35M;
   
       location / {
           proxy_pass http://127.0.0.1:3080;
           proxy_http_version 1.1;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           # Batch expense upload calls Gemini once per file; default 60s proxy timeout often returns 504
           proxy_connect_timeout 300s;
           proxy_send_timeout 300s;
           proxy_read_timeout 300s;
       }
   }

   Adjust server_name and 3080 if your ADMIN_PORT is different.

3. Reload nginx: sudo nginx -t && sudo systemctl reload nginx.

4. Point DNS for contador.example.com to this server’s IP.

5. For HTTPS, use Let’s Encrypt (e.g. certbot --nginx -d contador.example.com) or add an SSL block; Certbot can add the proxy headers if needed.

The setup does not configure nginx automatically (no install script or config file that edits nginx). You add the server block and DNS yourself so it works with your host and domain.

Update

To get the latest app version:

npm update el-contador
docker compose --project-directory node_modules/el-contador -f node_modules/el-contador/docker-compose.yml --env-file .env up -d --build

If npm update says "up to date" but a newer version is on npm (npm view el-contador version), install the latest explicitly then rebuild:

npm install el-contador@latest
docker compose --project-directory node_modules/el-contador -f node_modules/el-contador/docker-compose.yml --env-file .env up -d --build

Or use the CLI:

npx el-contador update

After a successful update, the backend log will show [email protected] (that version matches the release). Your data (database and uploads) lives in Docker volumes and is not overwritten by updates.

Commands (CLI)

• el-contador or el-contador start – start the stack (requires .env in current directory).
• el-contador down or el-contador stop – stop containers.
• el-contador update – run npm update el-contador then rebuild and start.

If npx el-contador fails with "docker compose (Compose V2) is required", install the Compose plugin. On Ubuntu the package is in Docker's repo (not default Ubuntu repos). Either add Docker's repository then sudo apt install docker-compose-plugin, or install the binary manually:

sudo mkdir -p /usr/local/lib/docker/cli-plugins
sudo curl -SL "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-$(uname -m)" -o /usr/local/lib/docker/cli-plugins/docker-compose
sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version

If you see KeyError: 'ContainerConfig' (Python traceback), you are using legacy docker-compose (V1). Install Docker Compose V2 as above; the CLI no longer falls back to V1.

If you see "compose build requires buildx 0.17.0 or later", the Docker Buildx plugin is missing or too old (e.g. 0.11 stuck from apt). Replace it with a newer binary. On 64-bit Linux, overwrite the existing plugin (usual path on Ubuntu/Debian):

BUILDX_VERSION=v0.32.1
# Where the old buildx usually lives when installed via apt:
BUILDX_DIR=/usr/lib/docker/cli-plugins
# If that dir doesn't exist, use: BUILDX_DIR=/usr/local/lib/docker/cli-plugins && sudo mkdir -p "$BUILDX_DIR"
sudo curl -SL "https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64" -o "${BUILDX_DIR}/docker-buildx"
sudo chmod +x "${BUILDX_DIR}/docker-buildx"
docker buildx version

If docker-buildx is in a different path (e.g. /usr/libexec/docker/cli-plugins), use that for BUILDX_DIR. On ARM64 use linux-arm64 instead of linux-amd64 in the URL. Then run npx el-contador again.

Publishing to npm (maintainers)

1. Create an npm account at npmjs.com/signup if needed.
2. Log in from the package root: npm login (username, password, email; OTP if 2FA is enabled).
3. Update repository.url in package.json to your real Git URL before publishing.
4. From this directory (the package root): npm publish --access public.
   --access public is required for unscoped packages. The package includes the full frontend/ source; the Docker image builds it at build time.
5. For later releases: bump version in both package.json (root) and server/package.json so the backend log shows the correct release (e.g. [email protected]), then npm publish from the package root.

License

MIT