Skip to content

Complete Deployment Guide - From Template to Production

Status: Production Ready v1.0
Last Updated: December 20, 2025
For: Organizations deploying Google Workspace using this template

📚 Table of Contents

  1. Overview
  2. Prerequisites
  3. Phase 1: Repository Setup
  4. Phase 2: Configuration
  5. Phase 3: Automation Scripts
  6. Phase 4: Data Files
  7. Phase 5: Validation
  8. Phase 6: Google Workspace Setup
  9. Phase 7: Team Onboarding
  10. Troubleshooting
  11. Post-Deployment

Overview

This guide walks through deploying Google Workspace infrastructure for a new organization using the workspace-setup-template. The template provides:

  • ✅ Reusable scripts for user/group management
  • ✅ Pre-built automation with PowerShell
  • ✅ Comprehensive documentation templates
  • ✅ Security best practices
  • ✅ Configuration validation tools

Total Time: 4-8 hours (depending on organization size)
Complexity: Medium (requires Google Admin access + PowerShell)

Prerequisites

Before starting, ensure you have:

  • [ ] Google Admin Account with Super Administrator role
  • [ ] GitHub Account with organization access
  • [ ] PowerShell 5.1+ installed (Windows 7+)
  • [ ] Git installed on your machine
  • [ ] Google Cloud Project created and configured
  • [ ] GAM (Google Apps Manager) v7.28+ installed
  • [ ] Organization's email domain ready
  • [ ] List of users & roles prepared
  • [ ] Approval to set up infrastructure

Software Installation

# Check PowerShell version
$PSVersionTable.PSVersion

# Install GAM (if not already installed)
# Follow: https://github.com/GAM-team/GAM/wiki/Installation

# Verify GAM installation
gam version

# Install Git (if not already installed)
# Download from: https://git-scm.com/download/win
git --version

Phase 1: Repository Setup (30 minutes)

Step 1.1: Create New GitHub Repository

  1. Go to https://github.com/Golfklubb-IT/repositories/new
  2. Fill in:
  3. Repository name: {ORG_SHORT}-workspace-setup (e.g., myclub-workspace-setup)
  4. Description: Google Workspace setup for {ORG_NAME}
  5. Visibility: Private (recommended for security)
  6. Initialize: Leave unchecked
  7. Click "Create repository"

Step 1.2: Clone This Template

# Navigate to your projects folder
cd C:\Users\YourName\Dev

# Clone the template repository
git clone https://github.com/Golfklubb-IT/workspace-setup-template.git

# Navigate into it
cd workspace-setup-template

# Change the remote to your organization's repository
git remote set-url origin https://github.com/YOUR-ORG/{ORG_SHORT}-workspace-setup.git

# Verify
git remote -v

Step 1.3: Push to Your Repository

# Push all branches and tags
git push -u origin main
git push origin v1.0
git push origin gh-docs  # Documentation branch

# Verify
git branch -a
git tag

Phase 2: Configuration (1-2 hours)

Step 2.1: Create Environment File

# Copy the template
Copy-Item .env.example .env

# Open in your editor
notepad .env

Step 2.2: Fill Configuration Values

Edit .env with your organization's values:

# === ORGANIZATION DETAILS ===
ORG_NAME=Your Organization Full Name
ORG_SHORT=YOURORG
DOMAIN=yourdomain.com
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_NAME=Your Admin Full Name
ADMIN_PHONE=+47-XXX-XXX-XX

# === GOOGLE CLOUD ===
GCP_PROJECT_ID=your-gcp-project-12345
GCP_FOLDER_ID=123456789012

# === GAM CONFIGURATION ===
GAM_ADMIN_EMAIL=admin@yourdomain.com
GAM_DOMAIN=yourdomain.com

# === EMAIL SETTINGS ===
SUPPORT_EMAIL=support@yourdomain.com
IT_EMAIL=it@yourdomain.com

# === DOCUMENTATION ===
DOC_SITE_URL=https://your-org.github.io/workspace-setup/
GITHUB_REPO=YOUR-ORG/workspace-setup
GITHUB_OWNER=YOUR-ORG

# === SECURITY SETTINGS ===
ENFORCE_2FA=true
MIN_PASSWORD_LENGTH=12
SESSION_TIMEOUT_MINUTES=30
YEAR=2025

Step 2.3: Verify Security

# Verify .env is in .gitignore
Get-Content .gitignore | Select-String ".env"

# Verify .env won't be committed
git status
# Should NOT show .env file

# CRITICAL: Never commit .env with real values!
git commit --allow-empty -m "Setup: .env configuration added (in .gitignore)"

Phase 3: Automation Scripts (30 minutes)

Step 3.1: Review Setup Script

# Read the setup script
Get-Content scripts/setup-new-org.ps1 | head -50

# This script will:
# - Read all configuration from .env
# - Replace {PLACEHOLDERS} in all files
# - Validate no unreplaced placeholders remain
# - Generate organization-specific configuration

Step 3.2: Run Setup Automation

# Navigate to scripts folder
cd scripts

# Execute setup script
.\setup-new-org.ps1

# The script will:
# 1. Load .env configuration
# 2. Display configuration summary for review
# 3. Replace placeholders across 60+ files
# 4. Verify all replacements successful
# 5. Generate detailed report

Example Output: 

=== Setup Complete ===
Organization: Your Organization Full Name
Domain: yourdomain.com
Files Updated: 34
Placeholders Replaced: 163
Status: ✅ SUCCESS

Step 3.3: Validate Setup

# Run validation script
.\validate-setup.ps1

# Checks:
# ✓ .env file exists and is readable
# ✓ .env in .gitignore
# ✓ All required data files present
# ✓ No unreplaced placeholders
# ✓ No security issues detected

Phase 4: Data Files (1-2 hours)

Step 4.1: Create Users File

Edit data/users.json:

[
  {
    "email": "john.doe@yourdomain.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "IT_ADMIN",
    "department": "IT",
    "manager": null
  },
  {
    "email": "jane.smith@yourdomain.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "EMPLOYEE",
    "department": "Sales",
    "manager": "john.doe@yourdomain.com"
  }
]

Roles: - IT_ADMIN - Full admin access - MANAGER - Can manage users in their department - EMPLOYEE - Standard user access

Step 4.2: Create Groups File

Edit data/groups.json:

[
  {
    "email": "all-staff@yourdomain.com",
    "name": "All Staff",
    "description": "All employees in organization",
    "type": "distribution"
  },
  {
    "email": "it-team@yourdomain.com",
    "name": "IT Team",
    "description": "IT Department team",
    "type": "security"
  }
]

Types: - distribution - Email distribution list - security - Security group for access control

Step 4.3: Create Organization Structure

Edit data/structure.json:

{
  "departments": [
    {
      "name": "IT",
      "manager": "john.doe@yourdomain.com",
      "members": ["john.doe@yourdomain.com"]
    },
    {
      "name": "Sales",
      "manager": "jane.smith@yourdomain.com",
      "members": ["jane.smith@yourdomain.com"]
    }
  ]
}

Phase 5: Validation (30 minutes)

Step 5.1: Pre-Deployment Checklist

# Verify all configuration
.\validate-setup.ps1

# Expected output:
# ✓ Environment file loaded
# ✓ All required variables present
# ✓ Data files valid JSON
# ✓ No security issues
# ✓ Ready for deployment

Step 5.2: Commit Configuration

# Stage all changes
git add .

# Commit
git commit -m "Setup: Configure for YOUR-ORG - customize placeholders and data files"

# Push to your repository
git push origin main

Phase 6: Google Workspace Setup (2-4 hours)

Step 6.1: Create Users in Google Admin

Option A: Using GAM Script 

# Navigate to scripts
cd scripts

# Run user creation (if automated script available)
.\create-users.ps1  # If available

Option B: Manual via Google Admin 1. Go to https://admin.google.com 2. Users and accounts → Users 3. Add new users 4. Use data/users.json as reference

Step 6.2: Create Email Groups

Using GAM: 

# Create group
gam create group all-staff@yourdomain.com name "All Staff"

# Add members
gam update group all-staff@yourdomain.com add members john.doe@yourdomain.com jane.smith@yourdomain.com

Or via Google Admin: 1. Groups → Create group 2. Name and email from data/groups.json 3. Add members

Step 6.3: Configure Shared Drives

Via Google Admin: 1. Apps → Google Workspace → Drive and Docs 2. Shared Drives → Create new 3. Share with appropriate groups from data/groups.json

Or using GAM (if available): 

# Create shared drive
gam create teamdrive "Department Name"

# Share with group
gam teamdrive "Department Name" add members group all-staff@yourdomain.com

Step 6.4: Apply Security Settings

In Google Admin Console: 1. Security → Authentication - Enforce 2FA (if ENFORCE_2FA=true) - Set password requirements: Minimum {MIN_PASSWORD_LENGTH} characters - Session timeout: {SESSION_TIMEOUT_MINUTES} minutes

  1. Security → Access and data control
  2. Review device policies

  3. Configure endpoint verification

  4. Rules → Create rules for security alerts

Phase 7: Team Onboarding (1-2 hours)

Step 7.1: Document Setup in Team Wiki

Create a team wiki page with: - Organization structure - Key contacts - Common procedures - Troubleshooting guide

Step 7.2: Schedule Training

  • Administrators: 2-hour training on GAM commands and group management
  • Users: 30-minute training on shared drives and collaboration tools
  • IT Team: 4-hour deep dive on security settings and troubleshooting

Step 7.3: Create Support Channels

  • Slack/Teams channel: #google-workspace-support
  • Email: {SUPPORT_EMAIL}
  • Documentation: {DOC_SITE_URL}

Troubleshooting

"PowerShell execution policy" Error

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

"Placeholder still unreplaced" Error

# Check for unreplaced placeholders
Get-ChildItem -Recurse -Include "*.json","*.ps1","*.md" | 
  Select-String -Pattern '\{[A-Z_]+\}' | 
  Select-Object -Property Filename, Line

"GAM permission denied" Error

# Re-authorize GAM
gam create oauth2.txt

"Git permission denied" Error

Use SSH instead of HTTPS: 

# Generate SSH key (if needed)
ssh-keygen -t ed25519 -C "admin@yourdomain.com"

# Change remote to SSH
git remote set-url origin git@github.com:YOUR-ORG/workspace-setup.git

# Test
ssh -T git@github.com

Post-Deployment

Step 1: Update Documentation

# Update the docs with organization-specific info
notepad docs/index.md

Step 2: Enable GitHub Pages

  1. Go to https://github.com/YOUR-ORG/workspace-setup/settings/pages
  2. Source: gh-docs branch
  3. Save

Your documentation will be available at: https://YOUR-ORG.github.io/workspace-setup/

Step 3: Set Up Backups

# Export users regularly
gam all users print > backups/users-$(Get-Date -Format yyyy-MM-dd).csv

# Export groups
gam all groups print > backups/groups-$(Get-Date -Format yyyy-MM-dd).csv

Step 4: Maintenance Schedule

  • Weekly: Review user/group changes
  • Monthly: Security audit via Google Admin
  • Quarterly: Update documentation
  • Annually: Review and update policies

Support & Questions

  • 📖 Full Documentation: {DOC_SITE_URL}
  • 📧 Support Email: {SUPPORT_EMAIL}
  • 💬 IT Team: {IT_EMAIL}
  • 🐛 Bug Reports: GitHub Issues
  • 💡 Feature Requests: GitHub Discussions

Version History

Version Date Changes
v1.0 Dec 20, 2025 Initial template release

Last Updated: December 20, 2025
Author: Golfklubb-IT
License: MIT