Skip to main content

Zyntem Fiscalization - Development Environment Setup

Company: Zyntem Product: Fiscalization by Zyntem Version: 1.0 Last Updated: 2025-10-30 Status: Active

Overview​

This guide will help you set up your local development environment for Fiscalization by Zyntem. Follow these steps in order to ensure all prerequisites are met before starting development.

Estimated Setup Time: 30-60 minutes (depending on what you already have installed)

Prerequisites​

Required Tools & Versions​

The following tools are required to develop Fiscalization by Zyntem. All version specifications are sourced from the architecture document (docs/architecture-tech-stack.md) and are mandatory for consistency across all development environments.

ToolVersion RequiredRationale
Go1.22.xMinor version pinning (1.22.x) ensures reproducible builds while allowing security patches ("same code + same dependencies = same binary"). Go 1.22.x provides strong typing to prevent runtime errors, excellent concurrency model (goroutines) for handling concurrent API requests, mature standard library, and first-class GCP support. Architecture mandates minor version pinning per Version Pinning Strategy.
Node.js18+ LTSRequired for Next.js 14 App Router used in the dashboard application. LTS version ensures stability and long-term support for production deployments.
PostgreSQL15+Pinned to major version 15 (not 16) for consistency per architecture decision. ACID compliance is critical for financial data integrity. JSONB support enables flexible storage of country-specific location configurations. Cloud SQL provides fully managed hosting.
Redis7.0+Enables accurate distributed rate limiting across multi-instance Cloud Run deployments. Reduces database load by 50%+ and prevents costly PostgreSQL upgrades. Token bucket rate limiting features require Redis 7.0+. CTO decision justifies $36.50/month Memorystore cost through database efficiency.
Docker24+Required for Docker Compose v2 syntax used in local development environment (Story 1.12).
Terraform1.7+Required for GCP provider compatibility with Cloud Run, Cloud SQL, Secret Manager, and Cloud Storage modules used in infrastructure provisioning (Stories 1.3a-c).
Git2.30+Version control and repository management.
GNU MakeAny recent versionBuild automation and task running.
jqAny recent versionJSON processing for API testing scripts.
curlAny recent versionHTTP client for API testing.

Version Pinning Strategy​

The project follows a strict version pinning strategy to ensure reproducibility and stability:

  • Go dependencies: Locked in go.mod with exact versions for reproducible builds
  • Security updates: Applied immediately via GitHub Dependabot alerts
  • Minor updates: Reviewed monthly for stability and compatibility
  • Major updates: Deferred to Phase 2 to maintain project stability during MVP development

Installation Instructions​

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install go node postgresql@15 redis docker terraform git jq

# Start PostgreSQL and Redis services
brew services start postgresql@15
brew services start redis

# Verify Docker Desktop is installed
open -a Docker

# Install version managers (optional but recommended)
brew install asdf  # Universal version manager
# OR
brew install nvm   # Node Version Manager
brew install gvm   # Go Version Manager

Version Managers (Recommended):

# Using asdf (manages all languages)
asdf plugin add golang
asdf plugin add nodejs
asdf install golang 1.22.0
asdf install nodejs 20.11.0
asdf global golang 1.22.0
asdf global nodejs 20.11.0

Linux (Ubuntu/Debian)​

# Update package list
sudo apt-get update

# Install Go 1.22.x (any patch version)
wget https://go.dev/dl/go1.22.0.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Install Node.js 18+ (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PostgreSQL 15+
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install -y postgresql-15

# Install Redis 7+
sudo add-apt-repository ppa:redislabs/redis
sudo apt-get update
sudo apt-get install -y redis

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Terraform 1.7+
wget https://releases.hashicorp.com/terraform/1.7.0/terraform_1.7.0_linux_amd64.zip
unzip terraform_1.7.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/

# Install other tools
sudo apt-get install -y git make jq curl

# Start services
sudo systemctl start postgresql
sudo systemctl start redis
sudo systemctl enable postgresql
sudo systemctl enable redis

Windows (WSL2 Required)​

Note: Native Windows development is not supported. You must use Windows Subsystem for Linux 2 (WSL2).

# Install WSL2 (PowerShell as Administrator)
wsl --install -d Ubuntu-22.04

# Restart computer
# After restart, open Ubuntu and follow Linux instructions above

Google Cloud Platform (GCP) Prerequisites​

Step 1: Create GCP Account​

  1. Visit https://cloud.google.com/
  2. Click "Get started for free"
  3. Complete account creation with valid credit card (free tier available)
  4. Verify billing is enabled

Step 2: Create GCP Project​

# Install gcloud CLI (if not already installed)
# macOS
brew install google-cloud-sdk

# Linux
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# Authenticate
gcloud auth login

# Create project
gcloud projects create zyntem-dev --name="Fiscalization Development"
gcloud config set project zyntem-dev

# Link billing account (replace BILLING_ACCOUNT_ID)
gcloud billing projects link zyntem-dev --billing-account=BILLING_ACCOUNT_ID

Step 3: Enable Required APIs​

gcloud services enable \
  run.googleapis.com \
  sqladmin.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com \
  cloudtrace.googleapis.com \
  monitoring.googleapis.com

Step 4: Create Service Account​

# Create service account
gcloud iam service-accounts create zyntem-dev \
  --display-name="Fiscalization Development Service Account"

# Grant required roles
gcloud projects add-iam-policy-binding zyntem-dev \
  --member="serviceAccount:zyntem-dev@zyntem-dev.iam.gserviceaccount.com" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding zyntem-dev \
  --member="serviceAccount:zyntem-dev@zyntem-dev.iam.gserviceaccount.com" \
  --role="roles/cloudsql.admin"

gcloud projects add-iam-policy-binding zyntem-dev \
  --member="serviceAccount:zyntem-dev@zyntem-dev.iam.gserviceaccount.com" \
  --role="roles/secretmanager.admin"

gcloud projects add-iam-policy-binding zyntem-dev \
  --member="serviceAccount:zyntem-dev@zyntem-dev.iam.gserviceaccount.com" \
  --role="roles/storage.admin"

# Download service account key
mkdir -p ~/.gcp
gcloud iam service-accounts keys create ~/.gcp/zyntem-dev-key.json \
  --iam-account=zyntem-dev@zyntem-dev.iam.gserviceaccount.com

# Set environment variable
echo 'export GOOGLE_APPLICATION_CREDENTIALS=~/.gcp/zyntem-dev-key.json' >> ~/.bashrc
source ~/.bashrc

Environment Validation​

Run the validation script to ensure all prerequisites are met:

# Clone repository first (if you haven't already)
git clone https://github.com/yourusername/fiscalization.git
cd fiscalization

# Run validation script
./scripts/validate-environment.sh

Expected Output:

✓ Go 1.22.x detected (required: 1.22.x)
✓ Node.js 20.11.0 detected
✓ PostgreSQL 15.5 detected
✓ Redis 7.2.3 detected
✓ Docker 24.0.7 detected
✓ Terraform 1.6.0 detected
✓ Git 2.42.0 detected
✓ make detected
✓ jq 1.7 detected
✓ curl 8.4.0 detected
✓ GCP credentials found at ~/.gcp/zyntem-dev-key.json

All prerequisites met! ✓
You are ready to start development.

Troubleshooting​

"Command not found" Errors​

Symptom: bash: go: command not found

Solution:

# Check if tool is installed
which go

# If not found, ensure PATH is set correctly
echo $PATH

# Add to PATH (example for Go)
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

Version Conflicts​

Symptom: Multiple versions of Go/Node installed

Solution: Use version managers (asdf, nvm, gvm) to manage versions:

# Example with asdf
asdf install golang 1.22.0
asdf global golang 1.22.0

PostgreSQL Connection Issues​

Symptom: could not connect to server: Connection refused

Solution:

# Check if PostgreSQL is running
# macOS
brew services list

# Linux
sudo systemctl status postgresql

# Start PostgreSQL
# macOS
brew services start postgresql@15

# Linux
sudo systemctl start postgresql

Docker Permission Denied​

Symptom: permission denied while trying to connect to the Docker daemon socket

Solution:

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and log back in
# Or use newgrp
newgrp docker

GCP Authentication Issues​

Symptom: ERROR: (gcloud.auth.login) There was a problem refreshing your credentials

Solution:

# Re-authenticate
gcloud auth login
gcloud auth application-default login

# Verify credentials
gcloud auth list

Next Steps​

Once all prerequisites are installed and validated:

  1. ✅ Read Testing Guide: docs/TESTING.md
  2. ✅ Clone Repositories: Follow Story 1.1 instructions
  3. ✅ Run Tests: make test (after Story 1.0b completion)
  4. ✅ Start Development: Begin Story 1.2

Additional Resources​

Support​

If you encounter issues not covered in this guide:

  1. Check GitHub Issues: https://github.com/zyntem/fiscalization/issues
  2. Ask in team Slack: #zyntem-dev
  3. Contact: javier.sanchez@zyntem.com