Troubleshooting

Requirements

Troy Server won't install if requirements aren't met:

Server Configuration

Set Up Real Cron

WP-Cron is unreliable for update servers. It only runs when someone visits your site. No visitors? No cron jobs.

For Troy Server, use a real server-side cron job:

define( 'DISABLE_WP_CRON', true );

* * * * * curl -s https://your-troy-server.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

curl -s https://your-troy-server.com/wp-cron.php?doing_wp_cron

Why every minute? Troy Server processes GitHub webhooks, cleans transients, and handles background tasks. Delayed cron means delayed releases.

Avoid Caching Plugins

Caching plugins break Troy Server's REST API responses. Users will receive stale or incorrect update data.

Specifically avoid:

• WP Super Cache, W3 Total Cache, LiteSpeed Cache
• Object caching plugins (Redis, Memcached) unless carefully configured
• Any plugin that caches REST API responses

If you need caching, use server-level caching (Nginx, Varnish) with proper REST API exclusions.

Avoid Translation Plugins

Translation plugins can interfere with Troy Server's output:

• REST API responses may get corrupted
• Plugin headers may be mistranslated
• JSON output may break

Troy Server doesn't need translation—it serves data to machines, not humans.

Plugin Distribution Issues

Users Can't Download

1. Plugin set to "Public"? Check the status in Troy Server admin
2. Pretty permalinks enabled? Settings → Permalinks → choose any non-plain option
3. Test the URL: https://your-server.com/plugin/get/zip/your-plugin

Updates Not Showing for Users

1. Troy Client installed? Updates require it
2. Troy header present? Check for Troy: your-server.com in the plugin file
3. Version higher? Server version must exceed installed version
4. URL matches exactly? your-server.com must match (no www unless your site uses it)

GitHub Integration

Repository Not Found

• Format: username/repository (not full URL)
• Private repos need a token with repo scope
• Check for typos

Releases Not Fetching

• Use semantic version tags: v1.0.0, not release-2024
• Create a Release, not just a tag
• If using webhooks, verify the URL and secret

Rate Limiting

Add a Personal Access Token—even for public repos. Increases limit from 60 to 5,000 requests/hour.

API Issues

REST API Returns 403

• Security plugins may block REST endpoints
• Check .htaccess for JSON blocking rules
• Verify WordPress isn't in maintenance mode

Slow Downloads

1. Avoid caching plugins (they cause more problems than they solve here)
2. Use a CDN for static assets (but exclude REST API)
3. Check server resources—upgrade if needed

File Recovery (Graveyard)

Accidentally deleted a plugin or package? Troy Server doesn't immediately destroy files—it moves them to a "graveyard" directory for manual recovery.

Where Files Go

When you delete a plugin or package from Troy Server:

The {id} corresponds to the plugin or package's internal database ID (visible in the admin URL when editing).

Recovery Steps

1. Find the graveyard folder for your deleted item
2. Copy the contents back to the active storage:
   • Plugins: wp-content/uploads/troy-plugins/plugin-{id}/
   • Packages: wp-content/uploads/troy-packages/package-{id}/
3. Restore the database entry (you'll need to re-add the plugin/package in the admin and match the ID, or restore from a database backup)

Prevention

Before deleting, consider setting the status to Disabled instead—this keeps files intact while blocking public access.

Getting Help

1. GitHub Issues — Bug reports
2. GitHub Discussions — Questions
3. Error logs — Always check server logs first

When reporting issues, include: WordPress version, PHP version, Troy Server version, and relevant error messages.