# GitHub and Hostinger Publishing Troubleshooting Guide

Purpose: Document the exact GitHub/Hostinger publishing problems encountered while deploying the GESD32 Vegeta documentation repository, the root causes identified, and the verified fixes that worked.

Owner: Technology Director, Gadsden Elementary School District 32

Repository: `vegetagesd32/vegeta-docs`

Local clone: `/path/to/vegeta-docs`

Operational identity used for commits: `Vegeta Operations <email@domain.com>`

Last updated: 2026-06-07

---

## 1. Executive Summary

The documentation repository initially failed when selected in Hostinger with this error:

```text
Unsupported framework or invalid project structure. Check files and supported frameworks.
```

The repository was also unable to push changes to GitHub using HTTPS because the Hermes/Vegeta environment had no GitHub credentials configured.

Both issues were resolved by:

1. Adding a minimal Node/static project structure to the repository.
2. Creating a repeatable build command: `npm run build`.
3. Building public output into `dist/`.
4. Excluding `internal/` from the public build.
5. Switching GitHub authentication from HTTPS to SSH.
6. Adding the Hermes/Vegeta SSH public key to GitHub.
7. Verifying SSH authentication and pushing to `main`.

---

## 2. Systems Involved

### 2.1 GitHub Repository

```text
vegetagesd32/vegeta-docs
```

Purpose:

- Store GESD32 Technology Department operational documentation.
- Maintain public-safe staff guides and internal documentation in separate paths.
- Publish selected documentation through Hostinger.

### 2.2 Local Repository Path

```text
/path/to/vegeta-docs
```

### 2.3 Hostinger

Purpose:

- Publish the documentation website from the GitHub repository.

### 2.4 Hermes/Vegeta Environment

Purpose:

- Create and maintain documentation.
- Commit changes.
- Push updates to GitHub.
- Support the Technology Director with operational documentation workflows.

---

## 3. Initial Problem: Hostinger Rejected the Repository

### 3.1 Error Message

Hostinger displayed:

```text
Unsupported framework or invalid project structure. Check files and supported frameworks.
```

### 3.2 Verified Repository Condition Before Fix

The repository had:

- `index.html`
- `README.md`
- `docs/`
- `public/`
- `internal/`
- `assets/`

The repository did not have:

- `package.json`
- A build script
- A standard build output directory
- A recognizable framework/static project structure for Hostinger auto-detection

### 3.3 Root Cause

Hostinger did not recognize the repository as a supported deployable project because the repository was a bare static documentation repository without a project manifest or build command.

### 3.4 Fix Applied

A minimal Node/static project structure was added.

Files added:

```text
package.json
scripts/build-static.js
scripts/serve-static.js
```

---

## 4. Static Build Structure That Worked

### 4.1 `package.json`

The repository now has a `package.json` that declares the project and build command.

Key settings:

```json
{
  "name": "vegeta-docs",
  "version": "1.0.0",
  "private": true,
  "description": "GESD32 Technology Department documentation site for Hostinger publishing.",
  "scripts": {
    "build": "node scripts/build-static.js",
    "start": "node scripts/serve-static.js"
  },
  "engines": {
    "node": ">=18"
  }
}
```

### 4.2 Build Script

File:

```text
scripts/build-static.js
```

Purpose:

- Delete and recreate `dist/`.
- Copy only public-safe publishing paths.
- Exclude internal documentation.

Published paths:

```text
index.html
docs/
public/
assets/
```

Excluded path:

```text
internal/
```

### 4.3 Local Preview Script

File:

```text
scripts/serve-static.js
```

Purpose:

- Serve the `dist/` folder locally for verification.
- Default local URL: `http://localhost:3000`

---

## 5. Build Verification

### 5.1 Command Used

```bash
npm run build
```

### 5.2 Successful Output

```text
Static documentation site built successfully into dist/.
Published paths: index.html, docs, public, assets
Excluded path: internal/
```

### 5.3 Hostinger Settings That Worked

Use these settings in Hostinger:

- Repository: `vegetagesd32/vegeta-docs`
- Branch: `main`
- Framework: Static site or Node.js/static, depending on the Hostinger screen
- Build command: `npm run build`
- Publish/output directory: `dist`
- Node version: 18 or newer

---

## 6. Security Boundary: Internal Documentation Exclusion

### 6.1 Problem Avoided

The repository contains both public-safe and internal documentation areas. Publishing everything could expose internal Technology Department material.

### 6.2 Fix Applied

The build script intentionally excludes:

```text
internal/
```

### 6.3 Operational Rule

Do not publish internal documentation unless access controls are verified.

Public-safe build paths:

```text
index.html
docs/
public/
assets/
```

Restricted path:

```text
internal/
```

---

## 7. Second Problem: GitHub Push Failed Over HTTPS

### 7.1 Failed Push Command

```bash
git push origin main
```

### 7.2 Error Message

```text
fatal: could not read Username for 'https://github.com': No such device or address
```

### 7.3 Verified Conditions

GitHub CLI was not installed:

```text
gh: command not found
```

GitHub token was not available:

```text
GITHUB_TOKEN_NOT_SET
```

Git credential store was missing:

```text
GIT_CREDENTIALS_MISSING
```

### 7.4 Root Cause

The local repository remote used HTTPS, but the Hermes/Vegeta environment did not have GitHub HTTPS credentials, a credential helper, a stored token, or GitHub CLI authentication.

---

## 8. GitHub Authentication Fix That Worked

### 8.1 Chosen Fix

SSH authentication was used instead of HTTPS token authentication.

Reason:

- `git` was available.
- `gh` was not installed.
- No `GITHUB_TOKEN` was configured.
- SSH avoids repeated HTTPS credential prompts.
- SSH is suitable for a persistent operational documentation environment.

### 8.2 SSH Key Generated

Commands used:

```bash
mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "email@domain.com" -f ~/.ssh/id_ed25519 -N ""
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
```

### 8.3 Public Key Added to GitHub

GitHub location:

```text
GitHub → Settings → SSH and GPG keys → New SSH key
```

Title used:

```text
Hermes Vegeta GESD32
```

Key type:

```text
Authentication Key
```

### 8.4 Remote Changed from HTTPS to SSH

Command used:

```bash
git remote set-url origin git@github.com:vegetagesd32/vegeta-docs.git
```

### 8.5 SSH Authentication Verification

Command used:

```bash
ssh -o StrictHostKeyChecking=accept-new -T git@github.com
```

Successful output:

```text
Hi vegetagesd32! You've successfully authenticated, but GitHub does not provide shell access.
```

---

## 9. Successful GitHub Push

### 9.1 Push Command

```bash
git push origin main
```

### 9.2 First Successful Commit Pushed

```text
6b56a8a build: add Hostinger-compatible static site scripts
```

### 9.3 Verified Remote Commit

Command:

```bash
git ls-remote origin main
```

Verified output:

```text
6b56a8a1290f7f2b459d9fccc87ae73cf7efaff3 refs/heads/main
```

### 9.4 Later Documentation Design Commit

The modern checklist guide was later added and pushed with:

```text
2907a86 docs: add Vegeta setup checklist page
```

---

## 10. Problems Found and Fixes Applied

### 10.1 Hostinger Invalid Project Structure

Problem:

```text
Unsupported framework or invalid project structure.
```

Cause:

- Bare static repository without `package.json` or build command.

Fix:

- Added `package.json`.
- Added `scripts/build-static.js`.
- Added `scripts/serve-static.js`.
- Configured Hostinger to use `npm run build` and `dist`.

Verification:

```bash
npm run build
```

### 10.2 Git Push Failed Over HTTPS

Problem:

```text
fatal: could not read Username for 'https://github.com': No such device or address
```

Cause:

- HTTPS remote required credentials.
- No GitHub token or credential helper was configured.
- Non-interactive Hermes environment could not prompt for username/password.

Fix:

- Generated SSH key.
- Added SSH public key to GitHub.
- Changed remote to SSH.

Verification:

```bash
ssh -T git@github.com
```

### 10.3 GitHub CLI Missing

Problem:

```text
gh: command not found
```

Cause:

- GitHub CLI was not installed on the server.

Fix:

- Did not require `gh`.
- Used pure `git` + SSH authentication.

Verification:

```bash
git push origin main
```

### 10.4 No GitHub Token Available

Problem:

```text
GITHUB_TOKEN_NOT_SET
```

Cause:

- No environment variable or token-based GitHub auth existed.

Fix:

- Used SSH key authentication instead of token authentication.

### 10.5 No Git Credential Store

Problem:

```text
GIT_CREDENTIALS_MISSING
```

Cause:

- `~/.git-credentials` did not exist.
- No stored HTTPS credentials were available.

Fix:

- Avoided HTTPS credential storage and used SSH.

### 10.6 Potential Internal Documentation Exposure

Problem:

- Repository contains `internal/` documentation.
- A naive static publish could expose internal documentation.

Fix:

- Build script excludes `internal/`.

Verification:

```text
Excluded path: internal/
```

---

## 11. Repeatable Procedure for Future Repositories

Use this procedure when publishing a documentation repository from GitHub to Hostinger.

### 11.1 Confirm Repository Structure

```bash
git status --short
git remote -v
```

Check for:

```text
package.json
scripts/build-static.js
index.html
```

### 11.2 Add Build Support If Missing

Create:

```text
package.json
scripts/build-static.js
scripts/serve-static.js
```

Minimum `package.json` pattern:

```json
{
  "name": "documentation-site",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "build": "node scripts/build-static.js",
    "start": "node scripts/serve-static.js"
  },
  "engines": {
    "node": ">=18"
  }
}
```

### 11.3 Verify Public Build

```bash
npm run build
```

Expected:

```text
Static documentation site built successfully into dist/.
```

### 11.4 Configure GitHub Authentication

Preferred for this Hermes/Vegeta environment:

```bash
git remote set-url origin git@github.com:OWNER/REPO.git
ssh -T git@github.com
```

### 11.5 Commit and Push

```bash
git add .
git commit -m "build: add Hostinger-compatible static site scripts"
git push origin main
git ls-remote origin main
```

### 11.6 Configure Hostinger

Use:

```text
Build command: npm run build
Output directory: dist
Node version: 18 or newer
Branch: main
```

---

## 12. Operational Controls

### 12.1 Do Not Commit Secrets

Never commit:

- API keys
- Bot tokens
- SSH private keys
- Passwords
- OAuth secrets
- `.env` files

### 12.2 Keep Private Key Local

The SSH private key stays on the server:

```text
~/.ssh/id_ed25519
```

Do not copy it into documentation, screenshots, commits, or chats.

### 12.3 Public Key Is Safe to Add to GitHub

The public key is stored at:

```text
~/.ssh/id_ed25519.pub
```

It can be added to GitHub as an authentication key.

### 12.4 Protect Internal Documentation

Keep confidential documentation in:

```text
internal/
```

Do not add `internal/` to the build script unless access controls are verified and the Technology Director approves.

---

## 13. Verification Checklist

Before telling the Technology Director the workflow is complete, verify:

- [ ] `npm run build` succeeds.
- [ ] `dist/` is generated.
- [ ] Build output excludes `internal/`.
- [ ] Git remote uses SSH or another verified authentication method.
- [ ] `ssh -T git@github.com` authenticates successfully.
- [ ] `git status --short` is clean after commit.
- [ ] `git push origin main` succeeds.
- [ ] `git ls-remote origin main` shows the expected commit.
- [ ] Hostinger settings use `npm run build` and `dist`.
- [ ] Published site loads successfully.

---

## 14. Known Good Commands From This Deployment

```bash
# Check repository status
git status --short
git remote -v
git log --oneline -3

# Build documentation site
npm run build

# Configure Git identity
git config --global user.name "Vegeta Operations"
git config --global user.email "email@domain.com"

# Generate SSH key
mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "email@domain.com" -f ~/.ssh/id_ed25519 -N ""
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

# Switch GitHub remote to SSH
git remote set-url origin git@github.com:vegetagesd32/vegeta-docs.git

# Verify GitHub SSH auth
ssh -o StrictHostKeyChecking=accept-new -T git@github.com

# Commit and push
git add .
git commit -m "build: add Hostinger-compatible static site scripts"
git push origin main

# Verify remote main
git ls-remote origin main
```

---

## 15. Final Working State

Verified working state after fixes:

- GitHub SSH authentication works.
- Repository pushes to GitHub successfully.
- Hostinger recognizes the repository after the Node/static structure was added.
- Hostinger build command works with `npm run build`.
- Public output is generated in `dist/`.
- Internal documentation is excluded from the public build.
- Modern checklist guide is linked from the homepage.

Operational note:

- If Hostinger shows the unsupported framework error again, first verify `package.json`, `npm run build`, and output directory `dist` before changing repository settings or recreating the deployment.