Skip to main content
This guide will help you install and configure CompanyFlow on your development machine or production server.

​
Prerequisites

Before you begin, ensure you have the following installed:

Go 1.24+

Download from golang.org

PostgreSQL 14+

Download from postgresql.org

Git

Download from git-scm.com
CompanyFlow requires Go version 1.24.0 or higher and PostgreSQL version 14 or higher.

​
Installation Steps

1

Clone the Repository

Clone the CompanyFlow repository from GitHub:
git clone https://github.com/falasefemi2/companyflowlow.git
cd companyflowlow
2

Install Dependencies

Download all required Go modules:
go mod download
This will install all dependencies including:
  • github.com/gorilla/mux - HTTP router
  • github.com/jackc/pgx/v5 - PostgreSQL driver
  • github.com/golang-jwt/jwt/v5 - JWT authentication
  • github.com/swaggo/swag - Swagger documentation
  • golang.org/x/crypto - Password hashing
3

Configure PostgreSQL Database

Create a new PostgreSQL database for CompanyFlow:
CREATE DATABASE companyflow;
You can use any database name you prefer. Just make sure to update the DB_NAME in your environment configuration.
4

Set Up Environment Variables

Create a .env file in the root directory with the following configuration:
# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_postgres_user
DB_PASSWORD=your_postgres_password
DB_NAME=companyflow
DB_SSLMODE=disable

# Server Configuration
PORT=8080

# CORS Configuration
CORS_ORIGIN=http://localhost:3000

# JWT Configuration
JWT_SECRET=your_secure_jwt_secret_key_here
Security Best Practices:
  • Use a strong, randomly generated JWT secret (minimum 32 characters)
  • Never commit the .env file to version control
  • In production, use environment variables instead of a .env file
  • Enable SSL mode (DB_SSLMODE=require) in production

​
Environment Variables Reference

VariableDescriptionRequiredDefault
DB_HOSTPostgreSQL host addressYes-
DB_PORTPostgreSQL portYes-
DB_USERDatabase usernameYes-
DB_PASSWORDDatabase passwordYes-
DB_NAMEDatabase nameYes-
DB_SSLMODESSL mode (disable/require/verify-full)Yes-
PORTServer portNo8080
CORS_ORIGINAllowed CORS originNohttp://localhost:3000
JWT_SECRETSecret key for JWT signingYes-
5

Run the Application

Start the CompanyFlow server:
go run main.go
On startup, CompanyFlow will:
  1. Connect to the PostgreSQL database
  2. Automatically run database migrations
  3. Start the HTTP server
You should see output similar to:
connecting to database
✓ Database connected successfully
Running migrations...
✓ Server starting on :8080
Press Ctrl+C to stop the server
6

Verify Installation

Test that the server is running correctly:
curl http://localhost:8080/health
You should receive an ok response.Then open your browser and navigate to the Swagger documentation:
http://localhost:8080/swagger/index.html

​
Database Migrations

CompanyFlow uses an automatic migration system that runs on startup.

​
How Migrations Work

  • Migration files are stored in database/migration/ as SQL files
  • Files are executed in alphabetical order based on their prefix (000_, 001_, etc.)
  • The system tracks executed migrations in a schema_migrations table
  • Each migration runs only once, even if you restart the server
Migrations are automatically executed when you run go run main.go. You don’t need to run them manually.

​
Migration File Structure

Migration files follow this naming pattern: 
000_create_companies_table.sql
001_create_employees_table.sql
002_create_departments_table.sql

​
Building for Production

To build a production-ready binary: 
go build -o companyflow main.go
This creates an executable binary called companyflow that you can deploy to your server.

​
Running the Production Binary

# Set environment variables
export DB_HOST=your-production-db-host
export DB_PORT=5432
export DB_USER=your-db-user
export DB_PASSWORD=your-db-password
export DB_NAME=companyflow
export DB_SSLMODE=require
export PORT=8080
export JWT_SECRET=your-production-jwt-secret
export CORS_ORIGIN=https://your-frontend-domain.com

# Run the binary
./companyflow
Production Checklist:
  • Use DB_SSLMODE=require for encrypted database connections
  • Set a strong, unique JWT secret
  • Configure CORS_ORIGIN to match your frontend domain
  • Use environment variables, not a .env file
  • Run behind a reverse proxy (nginx, Caddy, etc.)
  • Set up monitoring and logging

​
Running Tests

CompanyFlow includes a comprehensive test suite. To run tests: 
# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests for a specific package
go test ./repositories/...

# Run tests with coverage
go test -cover ./...

​
Test Database Configuration

For running tests, configure a separate test database using the TEST_DATABASE_URL environment variable or use the same DB_* variables with a different database name.

​
Docker Installation (Optional)

If you prefer using Docker, you can run PostgreSQL in a container: 
# Start PostgreSQL in Docker
docker run -d \
  --name companyflow-db \
  -e POSTGRES_USER=companyflow \
  -e POSTGRES_PASSWORD=companyflow \
  -e POSTGRES_DB=companyflow \
  -p 5432:5432 \
  postgres:14

# Update your .env file
DB_HOST=localhost
DB_PORT=5432
DB_USER=companyflow
DB_PASSWORD=companyflow
DB_NAME=companyflow

​
Troubleshooting

​
Connection Failed

Failed to initialize database: failed to ping database
Solutions:
  • Verify PostgreSQL is running: systemctl status postgresql (Linux) or check Activity Monitor (macOS)
  • Check database credentials in .env file
  • Ensure the database exists: psql -l
  • Verify PostgreSQL is accepting connections on the specified port

​
Migration Failed

Migration failed: pq: relation already exists
Solutions:
  • Drop and recreate the database for a clean slate
  • Check the schema_migrations table for inconsistencies
  • Ensure migration files are properly numbered

​
Port Already in Use

listen tcp :8080: bind: address already in use
Solutions:
  • Change the PORT in your .env file
  • Find and stop the process using port 8080: lsof -ti:8080 | xargs kill -9

​
Missing JWT Secret

Missing required environment variable: JWT_SECRET
Solution:
  • Add JWT_SECRET to your .env file with a secure random string

​
Next Steps

Now that CompanyFlow is installed and running, you’re ready to start using the API!

Quick Start

Make your first API calls and learn the basics

API Reference

Explore all available endpoints and schemas

Authentication

Learn about JWT authentication and security

Multi-Tenant Setup

Configure multiple companies in your instance

Build docs developers (and LLMs) love

Get started for freeTalk to us