Getting Started with Gogs Locally Using Git and Podman

Live stream set for 2025-11-02 at 14:00:00 Eastern

Ask questions in the live chat about any programming or lifestyle topic.

This livestream will be on YouTube or you can watch below.

Introduction to Gogs: Your Lightweight, Personal Git Service

Are you looking for a simple, fast, and easy way to host your own Git repositories? Meet Gogs, the open source “Go Git Service.” Think of it as your own personal, lightweight alternative to platforms like GitHub or GitLab, designed to be set up with minimal fuss on your own server.

Gogs is written in the Go language and is designed for simplicity and low resource consumption, making it perfect for smaller teams, personal projects, or even running on low-powered devices like a Raspberry Pi. Best of all, because it’s open source, you get full transparency and control over your code hosting environment.

Setting Up Gogs with Podman-Compose

Using containers is the easiest and most recommended way to install Gogs. We’ll use Podman-a daemonless container engine-and Podman-Compose-a tool for defining and running multi-container applications-to get Gogs and its database running quickly and securely.

Prerequisites

• Podman installed on your server/local machine.
• Podman-Compose (often installed via pip).
• A directory for your configuration files.

Step 1: Create a compose.yaml File

Create a file named compose.yaml (or docker-compose.yaml as Podman-Compose often supports Docker Compose files) to define your Gogs service and its required SQLite database volume. We’ll use the official Gogs image.

version: "3"

services:
  gogs:
    image: gogs/gogs
    container_name: gogs
    restart: always
    ports:
      - "3000:3000" # Web UI
      - "2222:22"   # SSH Access (Change Host Port if needed)
    volumes:
      # This volume stores all your repositories, configurations, and data.
      - gogs_data:/data 
    environment:
      # Optional: You can set the user Gogs runs as for rootless Podman
      - USER_UID=1000
      - USER_GID=1000

volumes:
  gogs_data:

Step 2: Start Gogs

Navigate to the directory containing your compose.yaml file and execute the following command:

podman-compose up -d

This command pulls the Gogs image (if not already local), creates the volume, and starts the container in the background (-d).

Step 3: Initial Setup

Open your web browser and navigate to the Gogs web interface. If you are running it on your local machine, this will typically be http://localhost:3000.

• Fill out the initial configuration form.
• For a simple setup, choose SQLite3 as the Database Type.
• Set the Run User to git (the default user inside the container).
• Set the Application URL to the external URL your users will use (e.g., http://your-server-ip:3000/).
• Crucially: Scroll down to create your first Admin Account.

Once configured, click Install Gogs.

Cloning and Pushing Your Code

After installation, create a new repository in your Gogs web interface (e.g., named my-first-repo). Gogs will provide you with the commands needed to clone and push your code.

Assuming your repository is called my-first-repo and your username is myuser, here are the standard Git commands you’ll use from your local development machine:

Cloning the Repository

To get a local copy of your new, empty repository (using HTTPS in this example):

# Replace 'your-server-ip:3000' and 'myuser/my-first-repo' with your details
git clone http://your-server-ip:3000/myuser/my-first-repo.git

Pushing Code to Gogs

1. Navigate into your new local repository directory:

   cd my-first-repo
   

2. Create an initial file and commit it:

   echo "# My First Gogs Project" >> README.md
   git add .
   git commit -m "Initial commit of README"
   

3. Push your local changes to your Gogs server:

   # 'origin' is the default name for the remote repository you cloned from
   git push origin master
   

You will be prompted for your Gogs username and password. After a successful push, refresh the repository page in Gogs to see your new file!

Screenshots and Screencast Tutorial

Level Up Your Programming Skills

Ready to take your development to the next level?

• Check out my programming books for in-depth knowledge:
  https://www.amazon.com/stores/Edward-Ojambo/author/B0D94QM76N
• Explore my comprehensive online programming courses:
  https://ojamboshop.com/product-category/course

Professional Support and Tutorials

Need personalized help with your coding journey or a professional setup of your Git service?

• I am available for one-on-one programming tutorials to accelerate your learning:
  https://ojambo.com/contact
• For businesses and individuals needing a robust solution, I offer professional Gogs installation with Git and repository migration services:
  https://ojamboservices.com/contact

Happy self-hosting!