Template Organization Setup Guide¶

Detailed walkthrough for configuring the template for your organization

Overview¶

This guide walks you through every step of adapting this template for your specific organization.

Time Estimate: 3-4 hours

Step 1: Prepare Your Environment (15 minutes)¶

1.1 Create Project Directory¶

cd c:\dev
git clone https://github.com/Golfklubb-IT/workspace-setup-template.git
cd workspace-setup-template

1.2 Create .env File¶

Copy-Item .env.example .env

1.3 Edit .env with Your Details¶

notepad .env

Fill in all required fields:

# Organization
ORG_NAME=Your Organization Name
ORG_SHORT=YourOrg
DOMAIN=yourdomain.com
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_NAME=Your Name
ADMIN_PHONE=+47-XXX-XXX-XX

# Google Cloud
GCP_PROJECT_ID=your-gcp-project-id
GCP_FOLDER_ID=12345

# Support
SUPPORT_EMAIL=support@yourdomain.com
IT_EMAIL=it@yourdomain.com

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

# Security
ENFORCE_2FA=true
MIN_PASSWORD_LENGTH=12
SESSION_TIMEOUT_MINUTES=30
PASSWORD_EXPIRY_DAYS=90

Step 2: Run Setup Script (10 minutes)¶

2.1 Execute Setup¶

.\scripts\setup-new-org.ps1

The script will: - Read your .env file - Replace all placeholders - Generate customized files - Report summary of changes

2.2 Review Changes¶

git status

Should show multiple files modified: - README.md - docs/*.md - data/structure.json - FORK_CHECKLIST.md - etc.

Step 3: Customize User & Group Lists (1 hour)¶

3.1 Define Users¶

Edit data/users.json:

[
  {
    "email": "john.doe@yourdomain.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "admin",
    "department": "IT",
    "title": "System Administrator",
    "recoveryEmail": "john@personal.com",
    "recoveryPhone": "+47-XXXXXXXX"
  },
  {
    "email": "jane.smith@yourdomain.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "manager",
    "department": "Finance",
    "title": "Finance Manager",
    "manager": "john.doe@yourdomain.com"
  }
]

Key fields: - email - Must use your domain - role - admin, manager, or member - department - For organization - manager - Email of supervisor

3.2 Define Groups¶

Edit data/groups.json:

[
  {
    "email": "admin@yourdomain.com",
    "displayName": "Administrators",
    "description": "System administrators",
    "managers": ["john.doe@yourdomain.com"],
    "members": ["john.doe@yourdomain.com"]
  },
  {
    "email": "finance@yourdomain.com",
    "displayName": "Finance Team",
    "description": "Finance department",
    "managers": ["jane.smith@yourdomain.com"],
    "members": ["jane.smith@yourdomain.com"]
  }
]

3.3 Define Shared Drives¶

Edit data/structure.json:

{
  "sharedDrives": [
    {
      "name": "Company Documents",
      "description": "Main organizational documents",
      "owners": ["john.doe@yourdomain.com"],
      "managers": ["jane.smith@yourdomain.com"],
      "structure": {
        "2025": {
          "Q1": {},
          "Q2": {}
        }
      }
    }
  ]
}

Step 4: Customize Documentation (1 hour)¶

4.1 Update Main README¶

Edit README.md: - Organization name - Your domain - Custom instructions - Contact information

4.2 Update Documentation Index¶

Edit docs/index.md: - Add organization-specific sections - Update contact information - Add custom links

4.3 Create Organization-Specific Docs¶

Add files like: - docs/YOUR_ORGANIZATION_PROCEDURES.md - docs/DEPARTMENT_STRUCTURE.md - docs/CUSTOM_WORKFLOWS.md

4.4 Update Configuration¶

Edit mkdocs.yml:

site_name: Your Organization Workspace
site_url: https://your-org.github.io/workspace/
docs_dir: docs/
site_dir: site/

Step 5: Set Up Google Cloud (30 minutes)¶

5.1 Create GCP Project¶

Go to console.cloud.google.com
Create new project: your-org-workspace-prod
Enable APIs:
Google Workspace Admin API
Directory API
Drive API
Groups Settings API

5.2 Create Service Account¶

Go to Service Accounts
Create new service account
Enable "Domain-wide Delegation"
Create JSON key
Save as gcp-service-account.json (in .gitignore!)

5.3 Configure GAM¶

# Install GAM from https://github.com/GAM-team/GAM

# Authorize
gam oauth create

# Verify
gam print users count

Create gam.cfg:

[DEFAULT]
domain = yourdomain.com
admin_email = admin@yourdomain.com
customer_id = C0xxxxx

Step 6: Commit Configuration (10 minutes)¶

6.1 Review Changes¶

git diff --stat

6.2 Commit¶

git add .
git commit -m "Setup: Configure workspace-setup template for Your Organization"

6.3 Verify No Secrets¶

git ls-files | Select-String "gam.cfg|oauth2.json|.env"

Should return nothing (files in .gitignore)

Step 7: Create GitHub Repository (20 minutes)¶

7.1 Create Repo on GitHub¶

Go to github.com
Create new private repository
Name: your-org-workspace or similar
Set as private
Don't initialize with README

7.2 Push Your Code¶

git remote set-url origin https://github.com/YOUR-ORG/your-org-workspace.git
git push -u origin main

7.3 Enable GitHub Pages (Optional)¶

For documentation site: 1. Settings → Pages 2. Deploy from: gh-pages branch 3. Save

Step 8: Test Configuration (30 minutes)¶

8.1 Run Validation¶

.\scripts\validate-setup.ps1

Should show all green: - ✅ .env file exists - ✅ No unreplaced placeholders - ✅ Required data files present - ✅ No secrets in repository

8.2 Test User Creation¶

# Create test user
gam create user test.user@yourdomain.com firstname Test lastname User password Test123456!

# Verify
gam print users email test.user@yourdomain.com

# Clean up
gam delete user test.user@yourdomain.com

8.3 Test Group Creation¶

# Create test group
gam create group testgroup@yourdomain.com name "Test Group"

# Verify
gam print groups email testgroup@yourdomain.com

# Clean up
gam delete group testgroup@yourdomain.com

Step 9: Documentation Site (Optional, 15 minutes)¶

9.1 Install MkDocs¶

pip install mkdocs mkdocs-material

9.2 Serve Locally¶

mkdocs serve

Visit http://127.0.0.1:8000

9.3 Deploy to GitHub Pages¶

mkdocs gh-deploy

Your site is now live at: https://your-org.github.io/workspace/

Step 10: Prepare for Deployment (15 minutes)¶

10.1 Final Checklist¶

[ ] All users defined in data/users.json
[ ] All groups defined in data/groups.json
[ ] All shared drives planned in data/structure.json
[ ] Documentation reviewed and customized
[ ] GAM tested and working
[ ] GCP configured with proper credentials
[ ] No secrets in Git repository
[ ] Team briefed on plan
[ ] Backup of old system completed
[ ] Support plan in place

10.2 Run All Scripts¶

# Create all users
.\automation\create-all-users.ps1

# Create all groups
.\automation\setup-all-groups.ps1

# Create all shared drives
.\automation\create-all-drives.ps1

# Set up permissions
.\automation\configure-all-permissions.ps1

10.3 Verify Deployment¶

.\automation\verify-deployment.ps1

Troubleshooting¶

Script won't run?

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Placeholders not replaced? - Verify .env file has all values - Re-run setup script - Check for typos in placeholder names

Can't authenticate GAM? - Verify GCP service account JSON is correct - Check domain-wide delegation is enabled - Try: gam info domain

Next Steps¶

Follow Migration Playbook for data migration
Create Training Materials for users
Set up Support Process
Plan Ongoing Maintenance

Completed setup? Congratulations! Your organization is ready to use Google Workspace.

Questions? See Troubleshooting or contact support.

Your Organization: {ORG_NAME}
Admin: {ADMIN_NAME}
Support: {SUPPORT_EMAIL}