# Quick Start - Docker Testing Environment The Docker build is running. Follow these steps once it completes: ## 1. Check Build Status ```bash # The build is running in the background # You can check if it's done with: docker images | grep gogs # If you see the image, the build is complete ``` ## 2. Start the Services ```bash # Start Gogs and PostgreSQL docker-compose -f docker-compose.test.yml up -d # Check that containers are running docker-compose -f docker-compose.test.yml ps # Expected output: # NAME STATUS PORTS # gogs-test Up (healthy) 0.0.0.0:10022->22/tcp, 0.0.0.0:10080->3000/tcp # gogs-test-postgres Up (healthy) 5432/tcp ``` ## 3. Watch the Logs ```bash # Follow Gogs logs docker-compose -f docker-compose.test.yml logs -f gogs # You should see: # - Database migration messages # - "Listen on http://0.0.0.0:3000" # - The GPG keys table (gpg_key) being created ``` ## 4. Access Gogs Open your browser and go to: **http://localhost:10080** Complete the installation wizard with these settings: ### Database Settings (pre-filled): - Database Type: **PostgreSQL** - Host: **postgres:5432** - User: **gogs** - Password: **gogs** - Database Name: **gogs** ### Application Settings: - Application Name: **Gogs** - Repository Root Path: **/home/git/gogs-repositories** (default) - Run User: **git** (default) - Domain: **localhost** - SSH Port: **10022** - HTTP Port: **3000** - Application URL: **http://localhost:10080/** ### Admin Account: - Username: **(your choice)** - Password: **(your choice)** - Email: **(your email)** Click **Install Gogs** ## 5. Verify GPG Keys Table Check that the database migration created the GPG keys table: ```bash # Access PostgreSQL docker exec -it gogs-test-postgres psql -U gogs -d gogs # Inside psql: \dt # List all tables (should see gpg_key) \d gpg_key # Describe the gpg_key table SELECT * FROM version; # Check migration version (should be 23 or higher) \q # Exit ``` Expected table structure: ``` Table "public.gpg_key" Column | Type | Collation | Nullable | Default ---------------+------------------------+-----------+----------+------------------------------------ id | bigint | | not null | nextval('gpg_key_id_seq'::regclass) owner_id | bigint | | not null | key_id | character varying(16) | | not null | fingerprint | character varying(40) | | not null | content | text | | not null | can_sign | boolean | | not null | false can_encrypt | boolean | | not null | false emails | text | | | created_unix | bigint | | | updated_unix | bigint | | | expired_unix | bigint | | | ``` ## 6. Generate API Token 1. Log in to Gogs 2. Go to **Settings** → **Applications** 3. Under "Generate New Token": - Token Name: **GPG Testing** 4. Click **Generate Token** 5. **Copy the token** (you won't see it again!) Save it as an environment variable: ```bash export GOGS_TOKEN="your_token_here" ``` ## 7. Test GPG Key Management API ### List GPG Keys (should be empty initially) ```bash curl -H "Authorization: token $GOGS_TOKEN" \ http://localhost:10080/api/v1/user/gpg_keys ``` Expected: `[]` ### Generate a Test GPG Key ```bash # Generate a test key (non-interactive) gpg --batch --gen-key < test-key.asc # View the key cat test-key.asc ``` ### Add GPG Key via API ```bash curl -X POST \ -H "Authorization: token $GOGS_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"armored_public_key\": \"$(cat test-key.asc | sed ':a;N;$!ba;s/\n/\\n/g')\"}" \ http://localhost:10080/api/v1/user/gpg_keys | jq ``` Expected response: ```json { "id": 1, "key_id": "ABCD1234567890EF", "fingerprint": "1234567890ABCDEF1234567890ABCDEF12345678", "primary_key_id": "ABCD1234567890EF", "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...", "emails": ["test@example.com"], "can_sign": true, "can_encrypt_comms": true, "can_encrypt_storage": true, "can_certify": true, "created": "2025-11-01T22:00:00Z" } ``` ### List GPG Keys Again ```bash curl -H "Authorization: token $GOGS_TOKEN" \ http://localhost:10080/api/v1/user/gpg_keys | jq ``` Should now show your key! ## 8. Test Signed Commits ```bash # Configure git git config --global user.name "Test User" git config --global user.email "test@example.com" git config --global user.signingkey $(gpg --list-secret-keys --keyid-format LONG test@example.com | grep sec | awk '{print $2}' | cut -d'/' -f2) git config --global commit.gpgsign true # Create a test repository via API curl -X POST \ -H "Authorization: token $GOGS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"gpg-test","description":"Testing GPG signatures","private":false}' \ http://localhost:10080/api/v1/user/repos # Clone it git clone http://localhost:10080/your-username/gpg-test.git cd gpg-test # Create a signed commit echo "# GPG Test" > README.md git add README.md git commit -m "Initial commit - GPG signed" # Verify signature locally git log --show-signature -1 # Push to Gogs (enter your Gogs username and password) git push origin main ``` ## 9. Verify in Database ```bash # Check that the GPG key is stored docker exec -it gogs-test-postgres psql -U gogs -d gogs -c \ "SELECT id, owner_id, key_id, fingerprint, can_sign, emails FROM gpg_key;" # Should show your imported key ``` ## 10. Test API Endpoints ### Get Specific Key ```bash curl -H "Authorization: token $GOGS_TOKEN" \ http://localhost:10080/api/v1/user/gpg_keys/1 | jq ``` ### Delete Key ```bash curl -X DELETE \ -H "Authorization: token $GOGS_TOKEN" \ http://localhost:10080/api/v1/user/gpg_keys/1 ``` ### Verify Deletion ```bash curl -H "Authorization: token $GOGS_TOKEN" \ http://localhost:10080/api/v1/user/gpg_keys | jq ``` Should return empty array `[]` ## Troubleshooting ### Build Failed ```bash # Check build logs docker-compose -f docker-compose.test.yml logs gogs # Rebuild from scratch docker-compose -f docker-compose.test.yml build --no-cache ``` ### Container Won't Start ```bash # Check all logs docker-compose -f docker-compose.test.yml logs # Check health status docker-compose -f docker-compose.test.yml ps ``` ### Database Connection Failed ```bash # Verify PostgreSQL is running docker-compose -f docker-compose.test.yml ps postgres # Check PostgreSQL logs docker-compose -f docker-compose.test.yml logs postgres # Test connection docker exec -it gogs-test-postgres psql -U gogs -d gogs -c "SELECT 1;" ``` ### API Returns 401 Unauthorized - Verify your token is correct - Check token wasn't deleted - Regenerate token in Gogs UI ### GPG Key Won't Import ```bash # Validate key format gpg --show-keys test-key.asc # Check key is properly armored head -1 test-key.asc # Should be: -----BEGIN PGP PUBLIC KEY BLOCK----- tail -1 test-key.asc # Should be: -----END PGP PUBLIC KEY BLOCK----- # Try exporting again gpg --armor --export test@example.com > test-key.asc ``` ## Cleanup ### Stop Services ```bash docker-compose -f docker-compose.test.yml stop ``` ### Remove Containers ```bash docker-compose -f docker-compose.test.yml down ``` ### Remove Everything (including data) ```bash docker-compose -f docker-compose.test.yml down -v ``` ## Success Checklist - [x] Docker containers built successfully - [ ] Gogs web UI accessible at http://localhost:10080 - [ ] Installation wizard completed - [ ] Admin account created - [ ] API token generated - [ ] GPG key table exists in database - [ ] GPG key added via API - [ ] GPG key visible in API response - [ ] Signed commit created - [ ] Commit pushed to Gogs - [ ] Database contains GPG key entry ## What's Working ✅ **Backend Implementation Complete:** - GPG key storage in PostgreSQL - REST API endpoints for key management - GPG signature parsing and extraction - Signature verification logic - Key expiration checking - Email-based author matching ⚠️ **UI Not Yet Implemented:** - No GPG key management page in web UI - No verification badges on commits - No visual indicators in commit history - API-only access for now ## Next Steps To add UI components, you would need to: 1. Create templates in `templates/user/settings/` 2. Add routes in `internal/route/user/` 3. Create commit badge templates 4. Add JavaScript for visual indicators For now, all functionality is accessible via the REST API! ## Documentation - Full testing guide: `TEST_GPG_VERIFICATION.md` - Feature documentation: `docs/features/gpg_verification.md` - API examples in this file Happy testing! 🎉