Skip to content

Installation

Go Overlay can be installed using multiple methods depending on your environment and preferences.

Installation Methods

Use Go Overlay as the entrypoint in your Dockerfile:

FROM ubuntu:22.04

# Download go-overlay
ADD https://github.com/srelabz/go-overlay/releases/latest/download/go-overlay /go-overlay

# Make it executable
RUN chmod +x /go-overlay

# Copy your services configuration
COPY services.toml /services.toml

# Set go-overlay as the entrypoint
ENTRYPOINT ["/go-overlay"]

Alpine-based example:

FROM alpine:3.22

# Download go-overlay
ADD https://github.com/srelabz/go-overlay/releases/latest/download/go-overlay /go-overlay

# Make it executable
RUN chmod +x /go-overlay

# Copy your services configuration
COPY services.toml /services.toml

# Set go-overlay as the entrypoint
ENTRYPOINT ["/go-overlay"]

Download the latest release directly using curl:

# Download the latest version
curl -L https://github.com/srelabz/go-overlay/releases/latest/download/go-overlay -o /go-overlay

# Make it executable
chmod +x /go-overlay

For a specific version:

# Replace VERSION with the desired version (e.g., v1.0.0)
VERSION=0.1.0
curl -L https://github.com/srelabz/go-entrypoint/releases/download/VERSION/go-overlay -o /go-overlay
chmod +x /go-overlay

Go Overlay includes an auto-installation feature that sets up the CLI tools automatically.

When you run go-overlay in daemon mode for the first time, it will:

  1. Create a symlink in /usr/local/bin/ for CLI access
  2. Set up the necessary permissions
  3. Configure the PATH automatically

To trigger auto-installation:

# Run in daemon mode (this will auto-install CLI tools)
go-overlay daemon

After auto-installation, you can use the CLI from anywhere:

# Check status of services
go-overlay status

# List all services
go-overlay list

# Restart a service
go-overlay restart <service-name>

PATH Configuration

The auto-installation process adds go-overlay to /usr/local/bin/, which is typically in your PATH. If you encounter issues, ensure /usr/local/bin/ is in your PATH:

export PATH="/usr/local/bin:$PATH"

Verification

After installation, verify that go-overlay is correctly installed:

# Check if go-overlay is accessible
which go-overlay

# Check the version
go-overlay --version

# View help information
go-overlay --help

Expected output:

$ which go-overlay
/go-overlay

$ go-overlay --version
go-overlay version x.x.x

Installation Complete

If you see the version information, go-overlay is successfully installed and ready to use!

Troubleshooting

Permission Denied

If you encounter permission errors:

# Ensure the binary is executable
chmod +x /go-overlay

# If installing to /usr/local/bin requires sudo
sudo chmod +x /go-overlay

Command Not Found

If the go-overlay command is not found:

  1. Verify the binary is in your PATH: 

    echo $PATH

  2. Add /usr/local/bin to your PATH if needed: 

    export PATH="/usr/local/bin:$PATH"

  3. Make the change permanent by adding it to your shell profile: 

    echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Docker Installation Issues

If you encounter issues in Docker:

  • Ensure curl is installed in your base image
  • Verify network connectivity during build
  • Check that the download URL is correct and accessible

Next Steps

Now that you have go-overlay installed, proceed to the Quick Start Guide to learn how to configure and run your first services.