Skip to content

local_setup.md

Latest commit

 

History

History
247 lines (162 loc) · 4.59 KB

local_setup.md

File metadata and controls

247 lines (162 loc) · 4.59 KB
Raw

Local Setup

This guide will help you set up the NimbusDb project on your local machine.

Prerequisites

Go Installation

This project requires Go 1.25 or later.

Recommended: Using asdf (Version Manager)

If you work with multiple Go projects that require different Go versions, we recommend using asdf to manage Go versions.

Installing asdf

macOS:

brew install asdf

Linux:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc

Windows (using WSL/Git Bash):

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc
Installing the Go Plugin
asdf plugin add golang
Basic asdf Usage
# Install a specific Go version
asdf install golang 1.25.0

# Set the global Go version (applies to all projects)
asdf global golang 1.25.0

# Set the local Go version (for this project only)
asdf local golang 1.25.0

# List installed Go versions
asdf list golang

# List all available Go versions
asdf list all golang

# Show current Go version
asdf current golang

# Update Go plugin to see latest versions
asdf plugin update golang

This project already has a .tool-versions file (which asdf will automatically pickup).

Verify Go Installation

From project root,

go version

Should output something like: go version go1.25.0 darwin/amd64

Alternative: Direct Go Installation

If you prefer a direct installation or don't need version management:

macOS:

brew install go

Linux:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y golang-go

# Fedora
sudo dnf install -y golang

Windows:

  1. Download the installer from golang.org/dl
  2. Run the installer and follow the prompts
  3. Verify installation: go version

From Source: Follow the instructions at golang.org/doc/install/source

Project Setup

Clone the Repository

git clone <repository-url>
cd NimbusDb

Install Dependencies

The project uses Go modules. Dependencies will be automatically downloaded when you build or test the project.

To explicitly download dependencies:

go mod download

To verify dependencies are correct:

go mod verify

Configuration & Secrets

  • A sample configuration file is given .config.yml
  • However secrets are recommended to be injected by a secret manager
  • If you are a Connection Loops employee then doppler file is already added for you. just run doppler setup to set it up.
  • To run the project with secrets being injected from doppler, run doppler run -- go run .

Build the Project

go build

This will create an executable in the current directory.

Run the Application

go run main.go

Or if you've built it:

./NimbusDb

Please make sure to supply the needed secrets see Configuration & Secrets section above.

Running Tests

Run All Tests

go test ./...

Run Tests in a Specific Package

go test ./configurations

Run Tests with Verbose Output

go test -v ./...

Run Tests with Coverage

# Run tests and generate coverage report
go test -cover ./...

# Generate detailed coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

This will open a coverage report in your browser showing which lines are covered by tests.

Run Specific Test Functions

# Run a specific test function
go test -run TestLoad_FromYAML ./configurations

# Run tests matching a pattern
go test -run TestLoad ./configurations

Run Tests in Watch Mode

For continuous testing during development, you can use tools like:

Using entr (Linux/macOS):

# Install entr
brew install entr  # macOS
# or: sudo apt-get install entr  # Linux

# Watch and run tests
find . -name "*.go" | entr -c go test ./...

Using air (with test configuration): Install air for a more full-featured testing experience.

Format with gofmt

Run

gofmt -l -w .

to auto-format code.

Troubleshooting

WIP

Additional Resources