Mastering Microservices PART 2: Creating a GitHub Repository from the Terminal Using Git and GitHub CLI

In Part 2 of the Mastering Microservices series, I'll guide you through establishing a strong version control system for your project using Git and GitHub. This is a fundamental step for effectively managing your codebase and promoting seamless collaboration, especially in complex projects like microservices applications. By the end of this guide, you'll have created a repository, organized your project structure, and pushed your initial code to GitHub, all from your terminal.

For this tutorial, we'll harness the power of Git and GitHub CLI (gh) directly from your Linux terminal. This method works seamlessly in environments like WSL (Windows Subsystem for Linux) or a Linux VM, providing you with a consistent and efficient workflow.

Choosing a Descriptive Repository Name

Before we get started, it's crucial to choose a repository name that accurately reflects your project's nature and purpose. Since we're building a microservices-based conference application, a fitting name would be:

conference-microservices-app

This name clearly communicates that the repository contains the code for a conference application built using a microservices architecture.

Step 1: Create the GitHub Repository Using GitHub CLI

To create and manage your repository from the terminal, we'll use GitHub CLI (gh). If you haven't installed it yet, please refer to Part 1: Setup Your Microservice Development Environment for installation instructions.

Configure Git

First, configure Git with your GitHub credentials:

git config --global user.name "your-username"
git config --global user.email "[email protected]"

Create the Repository:

1. Authenticate with GitHub CLI: Open your terminal and run the following command to authenticate with your GitHub account:

   gh auth login

   Follow the on-screen prompts to complete the authentication process.

2. Create the Repository: Once authenticated, create your new repository:

   gh repo create conference-microservices-app --public --source=. --remote=origin

   Here's a breakdown of this command:

   • conference-microservices-app: This is the name of your repository.
   • --public: Sets the repository's visibility to public. You can use --private if you need a private repository.
   • --source=.: This indicates that you want to create the repository in your current working directory.
   • --remote=origin: This configures a remote URL for your repository, typically named 'origin'.

After running this command, you'll see a link to your newly created GitHub repository!

Step 2: Initialize Your Project and Structure Your Codebase

Now that your repository is created, it's time to initialize a local Git repository and establish a well-organized project structure. A clear structure is essential for managing the various microservices that will make up your application.

Create the Directory Structure:

Navigate to the root of your project and create the following directories:

mkdir conference-microservices-app
cd conference-microservices-app
mkdir -p services/{frontend,c4p-service,agenda-service,notifications-service}
mkdir -p infrastructure/{kubernetes,terraform}
mkdir devbox
touch .gitignore README.md docker-compose.yml

This structure logically organizes your project:

• devbox/: This directory houses your Devbox environment configuration files, ensuring a consistent development environment for everyone on your team.
• services/: This folder contains the code for your individual microservices:
  • frontend/: This is for your frontend service (e.g., React, Angular, Vue.js).
  • c4p-service/: This is for the "Call for Papers" service (e.g., Node.js, Go).
  • agenda-service/: This is for managing the conference agenda (e.g., Node.js, Go).
  • notifications-service/: This is for handling notifications (e.g., Go with Kafka).
• infrastructure/: This directory holds your Infrastructure as Code (IaC) files:
  • kubernetes/: This is for your Kubernetes manifests, which you'll use to deploy the services.
  • terraform/: This is for your Terraform files, which manage cloud infrastructure.
• .gitignore: This file lists files and directories that Git should ignore.
• README.md: This file provides an overview of your project and includes instructions.
• docker-compose.yml: This file defines how to run your microservices together using Docker Compose.

Step 3: Initialize Git and Stage Your Files

Now, let's initialize Git and commit our initial project setup.

1. Initialize the Git Repository:

   git init

   This command creates a new, empty Git repository in your project directory.

2. Stage All Files:

   git add .

   This stages all files in your project directory, preparing them for your first commit.

3. Commit Your Changes:

   git commit -m "Initial project setup with folder structure"

   This permanently records your changes, creating the first commit in your project's history.

Step 4: Push Your Code to GitHub

Your local repository now has your initial project setup. Next, push these changes to the GitHub repository you created earlier.

1. Push to GitHub:

   git push origin main

   This command pushes the commits from your local main branch to the main branch of your remote repository named 'origin' (which you set up earlier with gh repo create).

   Note: If you initialized your repository with a different default branch name than 'main' (for example, 'master'), change the command accordingly.

After this push, your project is now available in your conference-microservices-app repository on GitHub!

Step 5: Create a .gitignore File

A .gitignore file is like a bouncer – it prevents unnecessary files from being committed to your repository. This keeps your repository clean and organized.

Add a .gitignore File:

Open your .gitignore file and add the following:

# Node.js
node_modules/
npm-debug.log

# Logs
logs/
*.log

# Docker
*.env
*.log
Dockerfile
.docker/

# Terraform
*.tfstate
*.tfstate.backup

# Kubernetes
.kube/

This tells Git to ignore:

• Node.js: node_modules/ (dependencies managed by package managers) and npm-debug.log files.
• Logs: Log files generated during development or runtime.
• Docker: Docker-related files like images, volumes, and build contexts.
• Terraform: Terraform state files, which may contain sensitive information.
• Kubernetes: Kubernetes configuration files.

Commit the .gitignore File:

Now, commit and push your .gitignore file:

git add .gitignore
git commit -m "Add .gitignore to exclude local files"
git push origin main

Step 6: Craft a Descriptive README.md

A well-written README.md file serves as the introduction to your project on GitHub. Let's add a clear and informative project description:

# Conference Microservices Application

This repository contains the codebase for our **Conference Microservices Application**. This application is designed with a microservices architecture and consists of these core components:

- **Frontend**: Provides a user-friendly interface built with [Frontend Framework - e.g., React, Angular, Vue.js].
- **C4P Service**: Manages the "Call for Papers" process, handling submissions from speakers.
- **Agenda Service**: Handles scheduling and displays conference sessions effectively.
- **Notifications Service**: Keeps attendees informed about conference updates and important announcements.

## Project Structure

conference-microservices-app/ │ ├── devbox/ # Devbox environment configuration │ ├── devbox.json # Devbox config for tools like Docker, Kubernetes, etc. │ └── ... │ ├── services/ # Microservices code │ ├── frontend/ # Frontend service (React, Angular, etc.) │ ├── c4p-service/ # Call for Papers service (Node.js/Go) │ ├── agenda-service/ # Agenda management service (Node.js/Go) │ └── notifications-service/ # Notifications service (Go, Kafka-based) │ ├── infrastructure/ # Infrastructure as Code (IaC) files │ ├── kubernetes/ # Kubernetes manifests for deploying services │ ├── terraform/ # Terraform files for cloud infrastructure │ └── ... │ ├── .gitignore # Git ignore file to exclude unnecessary files ├── README.md # Project overview and documentation └── docker-compose.yml # Docker Compose file for running microservices locally

## Getting Started

**To get started**, follow these instructions:

1. Clone the Repository:

   git clone [Your Repository URL]

2. Navigate to the Project Directory:

   cd conference-microservices-app

3. ... [Add more detailed setup steps, including how to install dependencies, configure the environment, and run the services]

## Contributing

Contributions are welcome! **Please** read our [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and how to submit pull requests.

## License

This project is licensed under the [License Name] - see the [LICENSE.md](LICENSE.md) file for details.

Commit and Push the README.md:

Finally, commit and push your README.md file:

git add README.md
git commit -m "Add initial README.md with project description and structure"
git push origin main

Conclusion

You have now successfully completed these key steps:

• Created a GitHub repository for your project.
• Initialized a local Git repository and structured your project effectively.
• Pushed your initial codebase to GitHub.
• Created a .gitignore file to exclude unnecessary files.
• Added a descriptive README.md file to guide visitors to your repository.

With these steps complete, you've built a strong foundation for your microservices project. In the next parts of this series, we'll start writing the code for individual microservices, starting with the frontend and C4P services.

GitHub Repository: Mastering Microservices with Azure, Docker, Kubernetes, Terraform, and GitHub Actions - specifically, check out the code for Part 2.