Skip to content

How to check for a new instance request

Jump to bottom
perennial edited this page May 16, 2024 · 14 revisions

When a new instance request is submitted, follow these steps to ensure the instance meets the requirements.

Feel free to edit this page if you have additional steps to suggest.

Tip

To get notifications for every new issue or comment in the repository, enable "watch repository" on GitHub:

Flowchart

🔀 Click to expand the flowchart 
graph TD
 A[New instance request submitted] --> B{Initial checks}
 B --> C{Source code modifications}
 C -->|Modifications found| D[Request modifications to be published]
 C -->|No modifications| E{Check for trackers or suspicious scripts}
 E -->|Trackers or suspicious scripts found| F[Request removal]
 E -->|No trackers or suspicious scripts| G{Security headers check}
 G -->|Missing or misconfigured headers| H[Request fixes]
 G -->|Headers properly configured| I{Post-install configuration}
 I -->|Incomplete configuration| J[Request completion]
 I -->|Configuration complete| K{Instance updates}
 K -->|Not up-to-date| L[Request update]
 K -->|Up-to-date| M{CDN usage}
 M -->|Using CDN| N[Verify CDN mentioned in 'Man in the Middle' section]
 M -->|No CDN| O{Tutorial completion}
 O -->|Tutorials not completed| P[Request tutorial completion]
 O -->|Tutorials completed| Q[Use GitHub labels to track status]
 Q --> R{After 30 days}
 R --> S{Review uptime}
 S -->|Unsatisfactory uptime| T[Notify instance owner to improve uptime]
 T --> U{Repeat initial checks}
 S -->|Satisfactory uptime| U{Repeat initial checks}
 U -->|Fails checks| V[Notify instance owner of issues]
 V --> W{Allow 14 days for corrections}
 W -->|Corrections made| U
 W -->|No corrections made| X[Fail instance]
 U -->|Passes checks| Y[Final approval - add to instances.md]
 Y --> Z[Close the issue]
Loading

Initial checks

1. Source code modifications

  • Examine the source code of the instance on key pages like the channel page, home page, and popular page.
  • Check for any modifications compared to a vanilla instance.
  • If modifications are found and the instance does not provide a source code URL, request the modifications to be published.

2. Check for trackers or suspicious scripts

  • Review the page source code for tracking scripts or suspicious scripts. If you find any, request that the instance owner remove them.
  • Scripts that appear strange or potentially malicious are not permitted. Common examples you may encounter are Cloudflare Web Analytics or Cloudflare JavaScript detections. However, there is also the possibility of more nefarious scripts like cryptominers or information stealers.
  • To help with identifying trackers and scripts, use the network tab in your web browser's developer tools or browser extensions like uBlock Origin or uMatrix. These tools can help reveal what scripts are loading and where they originate from.

3. Security headers check

  • Verify that the instance has properly configured security headers. This includes headers like Content-Security-Policy (CSP), Strict-Transport-Security (HSTS), X-Content-Type-Options, X-Frame-Options, etc.
    • A common misconfiguration is setting the HSTS header only on the subdomain serving the Invidious instance, rather than on the root domain. The HSTS header should be set on the root domain with the appropriate parameters:
      • max-age of at least 31536000 seconds (1 year)
      • includeSubDomains directive to apply HSTS to all subdomains of the root domain
      • preload directive to enable preloading, allowing browsers to hardcode the HTTPS requirement for the domain
    • Example of a properly configured HSTS header on the root domain: 
      Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
  • Use tools like Security Headers or Mozilla Observatory to audit the security headers.
  • If any critical security headers are missing or misconfigured, request the instance administrator to address them.

Note

The frame-ancestors directive in the Content-Security-Policy header obsoletes the X-Frame-Options header for browsers that support CSP. If a browser supports CSP, it will ignore the X-Frame-Options header when a frame-ancestors directive is present.

4. Post-install configuration

  • Verify that the instance has completed all the steps in the post-install configuration as outlined in the documentation, including settings like https_only, domain, etc.
  • Request the RSS feed of a channel (example on the yewtu.be instance). If https://theinstancedomain.com appears after <media:thumbnail url=", the configuration is correct.

5. Instance updates

  • Ensure the instance is up-to-date, preferably no more than 2 weeks old.
  • If not, request the instance to be updated and emphasize the importance of keeping it current.

6. CDN usage

  • Check if the instance is behind a CDN like Cloudflare. If so, verify that it is mentioned in the "Man in the Middle" section.

7. Tutorial completion

Use GitHub labels like passed-checks, passed-uptime, or failed-checks to assist maintainers in tracking the status of each instance.

After 30 days

1. Review uptime

Review the updown.io link to assess the instance's uptime over the last 30 days.

  • If the uptime is unsatisfactory, notify the instance owner to improve uptime before proceeding to the next step.

2. Repeat initial checks

Once the uptime is satisfactory, repeat the initial checks outlined above.

  • If the instance fails any of the checks, notify the instance owner of the specific issues that need to be corrected.
  • Allow 14 days for the instance owner to make the necessary corrections.
    • If corrections are made within 14 days, repeat the initial checks.
    • If no corrections are made after 14 days, fail the instance.
  • If the instance passes all checks, proceed to the next step.

3. Final approval

If the instance passes all checks:

  • Add it to the end of the list in the instances.md file. Mention Cloudflare usage if applicable.
  • Ask @unixfox and/or @TheFrenchGhosty for adding the maintainer to the matrix room for public instance maintainers. Only if the maintainer provided their matrix username in the GitHub issue.
  • Add the instance on the official status page: https://updown.io/status_pages/resvf/edit

4. Close the issue

Close the issue.

Clone this wiki locally