Update GITEA_SETUP.md with optional Docker configuration
- Document Docker installation on runner for image builds - Clarify that Docker is optional (not required for binary builds) - Add instructions for running the runner user with Docker permissions - Update troubleshooting section with Docker-specific guidance - Explain graceful handling when Docker is not available - Add Docker installation link in support section
This commit is contained in:
@@ -58,7 +58,7 @@ sudo systemctl restart gitea
|
||||
|
||||
## Setting Up a Runner (if needed)
|
||||
|
||||
If you don't have any runners yet, you need to set one up. This can be on the Gitea server itself or any machine with Docker/Go.
|
||||
If you don't have any runners yet, you need to set one up. This can be on the Gitea server itself or any machine with Docker and Go.
|
||||
|
||||
### Quick Runner Setup
|
||||
|
||||
@@ -84,45 +84,25 @@ To get a runner token:
|
||||
3. Click **Create new runner**
|
||||
4. Follow the registration steps
|
||||
|
||||
## Testing the Setup
|
||||
### Installing Docker on the Runner (Optional)
|
||||
|
||||
Once everything is configured:
|
||||
If you want to build Docker images as part of your releases, install Docker on the runner:
|
||||
|
||||
1. **Push a test tag**:
|
||||
```bash
|
||||
git tag -a v0.0.1-test -m "Test release"
|
||||
git push origin v0.0.1-test
|
||||
# Install Docker
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add permissions for the runner user to use Docker
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Verify Docker is working
|
||||
docker --version
|
||||
|
||||
# Note: You may need to logout and login for group permissions to take effect
|
||||
```
|
||||
|
||||
2. **Monitor the build**:
|
||||
- Go to Actions tab
|
||||
- You should see the workflow running
|
||||
- Check logs for any errors
|
||||
|
||||
3. **Verify the release**:
|
||||
- Go to Releases tab
|
||||
- You should see a new release with binaries and checksums
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Action not found" error
|
||||
- Make sure Gitea Actions is enabled
|
||||
- Restart Gitea if you just enabled it: `sudo systemctl restart gitea`
|
||||
|
||||
### No runners available
|
||||
- Runner must be registered: Administration → Actions → Runners
|
||||
- Runner machine must have Docker and Go installed
|
||||
- Check if runner is online in the UI
|
||||
|
||||
### "GITEA_TOKEN" not found
|
||||
- Make sure the secret is named exactly `GITEA_TOKEN` (case-sensitive)
|
||||
- Go to Settings → Secrets and verify it's there
|
||||
- If it's there, try re-running the workflow
|
||||
|
||||
### Build fails with permission denied
|
||||
- Make sure the runner has permission to run Docker commands
|
||||
- On the runner machine: `sudo usermod -aG docker $USER`
|
||||
- Logout and log back in for the group change to take effect
|
||||
**Without Docker**: The binary builds will still work. Only Docker image generation will be skipped (the workflow will show a warning but still succeed).
|
||||
|
||||
## What Happens Next
|
||||
|
||||
@@ -130,22 +110,51 @@ Once you've set everything up:
|
||||
|
||||
1. **Every push to main/master** triggers the build job:
|
||||
- Compiles all platform binaries
|
||||
- Builds Docker images
|
||||
- Attempts to build Docker images (skips if Docker unavailable)
|
||||
- Uploads artifacts as build artifacts
|
||||
|
||||
2. **Every git tag push** (e.g., `v1.0.0`) triggers the full release:
|
||||
- Does all of the above
|
||||
- Creates a Gitea Release
|
||||
- Uploads all binaries and Docker images to the release
|
||||
- Generates SHA256 checksums
|
||||
- Uploads all binaries and checksums to the release
|
||||
- Uploads Docker images if available
|
||||
|
||||
3. **Releases are available in**:
|
||||
- Repository Releases tab in Gitea
|
||||
- Binaries ready for download
|
||||
- Docker images ready for import
|
||||
- Docker images (if Docker is available on runner)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "docker: command not found" in workflow
|
||||
- Docker is not installed on your runner
|
||||
- This is **optional** - binaries will still build
|
||||
- If you want Docker images, install Docker on the runner (see above)
|
||||
- The workflow will gracefully skip Docker builds and show a warning
|
||||
|
||||
### "Action not found" error
|
||||
- Make sure Gitea Actions is enabled
|
||||
- Restart Gitea if you just enabled it: `sudo systemctl restart gitea`
|
||||
|
||||
### No runners available
|
||||
- Runner must be registered: Administration → Actions → Runners
|
||||
- Runner machine must have Go installed (1.24.4 or later)
|
||||
- Docker is optional (for building Docker images)
|
||||
- Check if runner is online in the UI
|
||||
|
||||
### "GITEA_TOKEN" not found
|
||||
- Make sure the secret is named exactly `GITEA_TOKEN` (case-sensitive)
|
||||
- Go to Settings → Secrets and verify it's there
|
||||
- If it's there, try re-running the workflow
|
||||
|
||||
### Build fails with permission denied (Docker)
|
||||
- Make sure the runner user has permission to run Docker commands
|
||||
- On the runner machine: `sudo usermod -aG docker $USER`
|
||||
- Logout and log back in for the group change to take effect
|
||||
|
||||
## Support
|
||||
|
||||
- Gitea Actions Docs: https://docs.gitea.io/en-us/actions/
|
||||
- Act Runner Docs: https://gitea.com/gitea/act_runner
|
||||
- Docker Installation: https://docs.docker.com/install/
|
||||
- For issues with the workflow itself, check the Actions tab logs
|
||||
|
||||
Reference in New Issue
Block a user