Skip to content

MAC_LINUX_SETUP_GUIDE.md

Latest commit

 

History

History
260 lines (171 loc) · 5.35 KB

MAC_LINUX_SETUP_GUIDE.md

File metadata and controls

260 lines (171 loc) · 5.35 KB

🛠️ Mac and Linux Development Setup Guide for DocMagic

Welcome to the DocMagic contributor community! 🎉
This guide is designed for beginners who may have never contributed to an open-source project before. It will walk you through every step required to set up the development environment on macOS and Linux, so you can start contributing confidently to this AI-powered document generation platform.

📚 Table of Contents

📆 Prerequisites

Before you begin, ensure you have the following:

  • A GitHub account: Sign up here
  • Basic familiarity with opening a terminal (Command Line Interface)
  • Admin rights on your machine (to install tools)

✅ Step 1: Install a Package Manager

🍎 macOS – Homebrew

Homebrew is a popular package manager that simplifies installing software on macOS.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Verify installation:

brew --version

🐧 Linux – APT (Ubuntu/Debian)

APT is the default package manager on most Debian-based Linux systems.

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl file git

🔧 Step 2: Install Git

Git is used to track code changes and collaborate with others.

macOS

brew install git

Linux

sudo apt install git

Verify installation:

git --version

🧰 Step 3: Install Node.js and npm via NVM

NVM (Node Version Manager) helps manage multiple Node versions easily.

3.1 Install NVM

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Then activate NVM:

source ~/.bashrc   # or ~/.zshrc

3.2 Install Node.js (Latest LTS)

nvm install --lts
nvm use --lts

Verify:

node -v
npm -v

💻 Step 4: Terminal & Shell Setup (Optional but Recommended)

macOS

Install Zsh + Oh My Zsh:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Add Powerlevel10k:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ~/powerlevel10k
echo 'source ~/powerlevel10k/powerlevel10k.zsh-theme' >> ~/.zshrc

Linux

sudo apt install zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

🧑‍💻 Step 5: Install VS Code and Extensions

macOS

brew install --cask visual-studio-code

Linux

sudo snap install code --classic

Recommended Extensions

  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • GitLens
  • Markdown All in One
  • DotENV

📂 Step 6: Clone and Set Up the Project

Step 6.1: Fork the Repository

Go to https://github.com/Muneerali199/DocMagic and click the Fork button.

Step 6.2: Clone Your Fork

git clone https://github.com/YOUR_USERNAME/DocMagic.git
cd DocMagic

Replace YOUR_USERNAME with your actual GitHub username.

Step 6.3: Install Dependencies

npm install

⚙️ Step 7: Setup Environment Variables

Copy the example file

cp .env.local.example .env.local

Edit .env.local and add:

  • Supabase keys
  • Google API keys
  • Any other required environment variables

Ask maintainers if you need development sample credentials.

🚀 Step 8: Run the Project Locally

npm run dev

Visit the app locally in your browser:

http://localhost:3000

🎨 Step 9: Optional Dev Enhancements

  • Terminal Themes: Dracula, One Dark, Nord
  • VS Code Themes: GitHub Dark, Night Owl, Monokai Pro
  • Shell Plugins: autosuggestions, syntax highlighting

🧪 Step 10: Common Issues & Fixes

❌ npm install Errors

rm -rf node_modules
npm cache clean --force
npm install

❌ Node or npm not recognized

nvm use

🤝 Need Help?

  • Refer to README.md and CONTRIBUTING.md
  • Comment under your assigned GitHub issue
  • Join the community Discord or reach out to project mentors

Made with ❤️ by the DocMagic community.

Happy coding and welcome aboard! 🚀