GWorkspace Toolbox

A comprehensive, open-source toolkit for Google Workspace administrators with tools for user management, group synchronization, and attribute injection.

🚀 Features automatic updates • 🌍 Multi-language support • 🐳 Docker-ready • 🔒 Branch-protected

Features

Google Workspace Tools

1. Alias Extractor

Extract all user accounts with email aliases from Google Workspace and export to CSV format.

Output Format:

• Current Email
• Alias 1
• Alias 2
• Alias 3
• (Additional aliases as needed)

Supported Languages

• English
• Spanish (Español)
• Portuguese (Português)

Deployment Options

Local Development

Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Frontend Setup

cd frontend
npm install
npm run dev

Google Workspace API Setup

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the Admin SDK API
4. Create OAuth 2.0 credentials (Desktop app)
5. Download the credentials JSON file
6. Upload it through the application interface

Docker Deployment (Recommended)

Docker deployment includes automatic updates via Watchtower - you'll always have the latest version!

# Pull and run pre-built image
docker-compose up -d

# Access the application
# UI + API: http://localhost:8000

What's included:

• ✅ Single unified image (frontend + backend) from GitHub Container Registry
• ✅ Automatic updates (checks daily for new versions)
• ✅ Auto-cleanup of old images
• ✅ No manual updates needed!
• ✅ Access at http://localhost:8000 (both UI and API)

Manual update (if needed):

docker-compose pull
docker-compose up -d

For local development (build from source):

docker-compose -f docker-compose.dev.yml up

Architecture

GWorkspace-toolbox/
├── backend/          # FastAPI Python backend
├── frontend/         # React + Vite frontend
├── docker-compose.yml
└── README.md

API Documentation

Once running, access the interactive API documentation at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Security Notes

• Never commit credentials.json or token.json files
• Store sensitive credentials securely
• Use environment variables for configuration
• The application runs locally to maintain credential security

Contributing

We welcome contributions from the community! 🎉

🐛 Found a Bug?

Open an issue with details about the problem.

💡 Have an idea?

Submit a feature request or start a discussion.

🔨 Want to contribute code?

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Push to your branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Note: The main branch is protected and requires:

• ✅ Pull Request review and approval
• ✅ CI/CD checks to pass (Docker builds)
• ✅ No direct pushes allowed

See CONTRIBUTING.md for detailed guidelines.

CI/CD Pipeline

This project uses GitHub Actions for continuous integration:

• ✅ Automatic Docker image builds on every push to main
• ✅ Images published to GitHub Container Registry
• ✅ Watchtower automatically updates running instances
• ✅ Branch protection ensures code quality

View builds: GitHub Actions

Community & Support

• 📫 Report Issues
• 💬 Discussions
• 📖 Documentation

License

MIT License - see LICENSE for details

---

Made with ❤️ for Google Workspace administrators