Quick Start - Docker Testing Environment

The Docker build is running. Follow these steps once it completes:

1. Check Build Status

# 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

# 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

# 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:

# 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

Log in to Gogs
Go to Settings → Applications
Under "Generate New Token":
- Token Name: GPG Testing
Click Generate Token
Copy the token (you won't see it again!)

Save it as an environment variable:

export GOGS_TOKEN="your_token_here"

7. Test GPG Key Management API

List GPG Keys (should be empty initially)

curl -H "Authorization: token $GOGS_TOKEN" \
  http://localhost:10080/api/v1/user/gpg_keys

Expected: []

Generate a Test GPG Key

# Generate a test key (non-interactive)
gpg --batch --gen-key <<EOF
Key-Type: RSA
Key-Length: 2048
Subkey-Type: RSA
Subkey-Length: 2048
Name-Real: Test User
Name-Email: test@example.com
Expire-Date: 0
%no-protection
EOF

# List keys
gpg --list-keys

# Export public key
gpg --armor --export test@example.com > test-key.asc

# View the key
cat test-key.asc

Add GPG Key via API

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:

{
  "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

curl -H "Authorization: token $GOGS_TOKEN" \
  http://localhost:10080/api/v1/user/gpg_keys | jq

Should now show your key!

8. Test Signed Commits

# 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

# 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

curl -H "Authorization: token $GOGS_TOKEN" \
  http://localhost:10080/api/v1/user/gpg_keys/1 | jq

Delete Key

curl -X DELETE \
  -H "Authorization: token $GOGS_TOKEN" \
  http://localhost:10080/api/v1/user/gpg_keys/1

Verify Deletion

curl -H "Authorization: token $GOGS_TOKEN" \
  http://localhost:10080/api/v1/user/gpg_keys | jq

Should return empty array []

Troubleshooting

Build Failed

# 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

# 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

# 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

# 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

docker-compose -f docker-compose.test.yml stop

Remove Containers

docker-compose -f docker-compose.test.yml down

Remove Everything (including data)

docker-compose -f docker-compose.test.yml down -v

Success Checklist

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:

Create templates in templates/user/settings/
Add routes in internal/route/user/
Create commit badge templates
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! 🎉

QUICK_START_DOCKER.md 9.0 KB Geschiedenis Ruwe