Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/configuration/configuring_file_domain.diviner
@title Configuring a File Domain | @title Configuring a File Domain | ||||
@group config | @group config | ||||
Setup guide for an alternate file domain or CDN. | Setup guide for an alternate file domain or CDN. | ||||
Overview | Overview | ||||
======== | ======== | ||||
Serving files that users upload from the same domain that Phabricator runs on | Serving files that users upload from the same domain that Phorge runs on | ||||
is a security risk. | is a security risk. | ||||
In general, doing this creates a risk that users who have permission to upload | In general, doing this creates a risk that users who have permission to upload | ||||
files may be able to upload specially crafted files (like Flash or Java | files may be able to upload specially crafted files (like Flash or Java | ||||
applets) which can execute with domain permissions in some contexts (usually | applets) which can execute with domain permissions in some contexts (usually | ||||
because of security issues with Flash and Java, but both products have a rich | because of security issues with Flash and Java, but both products have a rich | ||||
history of security issues). The attacker can then trick another user into | history of security issues). The attacker can then trick another user into | ||||
executing the file and gain access to their session. | executing the file and gain access to their session. | ||||
The best way to mitigate this threat is to serve files from a separate domain. | The best way to mitigate this threat is to serve files from a separate domain. | ||||
For example, if Phabricator is hosted at `https://phabricator.example.com/`, | For example, if Phorge is hosted at `https://phorge.example.com/`, | ||||
you can serve files from `https://files.exampleusercontent.com/`. | you can serve files from `https://files.exampleusercontent.com/`. | ||||
The alternate file domain should be a completely different domain from your | The alternate file domain should be a completely different domain from your | ||||
primary domain, not just a different subdomain. For example, Google uses | primary domain, not just a different subdomain. For example, Google uses | ||||
`googleusercontent.com`, //not// `usercontent.google.com`. | `googleusercontent.com`, //not// `usercontent.google.com`. | ||||
You can also configure the alternate file domain to serve through a CDN, which | You can also configure the alternate file domain to serve through a CDN, which | ||||
will improve performance. | will improve performance. | ||||
Show All 14 Lines | |||||
Approach: AWS CloudFront | Approach: AWS CloudFront | ||||
======== | ======== | ||||
CloudFront is a CDN service that's part of Amazon Web Services. It makes | CloudFront is a CDN service that's part of Amazon Web Services. It makes | ||||
particular sense to use if you're hosting your install in AWS. | particular sense to use if you're hosting your install in AWS. | ||||
To configure it, set up a new CloudFront distribution which is pointed at | To configure it, set up a new CloudFront distribution which is pointed at | ||||
your Phabricator install as an origin (make sure you point it at the primary | your Phorge install as an origin (make sure you point it at the primary | ||||
domain name of your install, not just a load balancer or instance). You do not | domain name of your install, not just a load balancer or instance). You do not | ||||
need to set up a new domain name, which makes setup a bit more straightforward. | need to set up a new domain name, which makes setup a bit more straightforward. | ||||
Most settings can be left at their default values, but you should change | Most settings can be left at their default values, but you should change | ||||
the **Allowed HTTP Methods** setting from `GET, HEAD` to | the **Allowed HTTP Methods** setting from `GET, HEAD` to | ||||
`GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`. | `GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE`. | ||||
Once configured, accessing the distribution's domain name should return a | Once configured, accessing the distribution's domain name should return a | ||||
Phabricator error page indicating that Phabricator does not recognize the | Phorge error page indicating that Phorge does not recognize the | ||||
domain. If you see this page, it means you've configured things correctly. | domain. If you see this page, it means you've configured things correctly. | ||||
Continue to "Configuring Phabricator", below. | Continue to "Configuring Phorge", below. | ||||
Approach: CloudFlare | Approach: CloudFlare | ||||
======== | ======== | ||||
WARNING: You should review all your CloudFlare settings, and be very | WARNING: You should review all your CloudFlare settings, and be very | ||||
sure to turn off all JavaScript, HTML, CSS minification and | sure to turn off all JavaScript, HTML, CSS minification and | ||||
optimization features, including systems like "Rocket Loader". These | optimization features, including systems like "Rocket Loader". These | ||||
features will break Phabricator in strange and mysterious ways that | features will break Phorge in strange and mysterious ways that | ||||
are unpredictable. Only allow CloudFlare to cache files, and never | are unpredictable. Only allow CloudFlare to cache files, and never | ||||
optimize them. | optimize them. | ||||
[[ https://cloudflare.com | CloudFlare ]] is a general-purpose CDN service. | [[ https://cloudflare.com | CloudFlare ]] is a general-purpose CDN service. | ||||
To set up CloudFlare, you'll need to register a second domain and go through | To set up CloudFlare, you'll need to register a second domain and go through | ||||
their enrollment process to host the alternate domain on their servers. Use a | their enrollment process to host the alternate domain on their servers. Use a | ||||
CNAME record to forward a subdomain to your Phabricator install. | CNAME record to forward a subdomain to your Phorge install. | ||||
CloudFlare will automatically generate SSL certificates for hosted domains, | CloudFlare will automatically generate SSL certificates for hosted domains, | ||||
which can significantly reduce the cost and complexity of setup. | which can significantly reduce the cost and complexity of setup. | ||||
Once configured, accessing the CNAME-forwarded subdomain should return a | Once configured, accessing the CNAME-forwarded subdomain should return a | ||||
Phabricator error page indicating that Phabricator does not recognize the | Phorge error page indicating that Phorge does not recognize the | ||||
domain. If you see this page, it means you've configured things correctly. | domain. If you see this page, it means you've configured things correctly. | ||||
Continue to "Configuring Phabricator", below. | Continue to "Configuring Phorge", below. | ||||
Approach: Self Hosted | Approach: Self Hosted | ||||
======== | ======== | ||||
To do this, just set up a second domain exactly like your primary domain is | To do this, just set up a second domain exactly like your primary domain is | ||||
set up. When setup is complete, visiting the domain should return a Phabricator | set up. When setup is complete, visiting the domain should return a Phorge | ||||
error page indicating that Phabricator does not recognize the domain. This | error page indicating that Phorge does not recognize the domain. This | ||||
means that you've configured things correctly. | means that you've configured things correctly. | ||||
Note that if you use SSL (which you should), you'll also need to get a | Note that if you use SSL (which you should), you'll also need to get a | ||||
certificate for this alternate domain and configure that, too. | certificate for this alternate domain and configure that, too. | ||||
You can also configure a self-hosted domain to route through a caching server | You can also configure a self-hosted domain to route through a caching server | ||||
to provide some of the performance benefits of a CDN, but this is advanced and | to provide some of the performance benefits of a CDN, but this is advanced and | ||||
outside the scope of this documentation. | outside the scope of this documentation. | ||||
Continue to "Configuring Phabricator", below. | Continue to "Configuring Phorge", below. | ||||
Configuring Phabricator | Configuring Phorge | ||||
======== | ======== | ||||
After you've set up a CDN or an alternate domain, configure Phabricator to | After you've set up a CDN or an alternate domain, configure Phorge to | ||||
recognize the domain. Run this command, providing the domain you have | recognize the domain. Run this command, providing the domain you have | ||||
configured in place of the `<domain>` token. You should include the protocol, | configured in place of the `<domain>` token. You should include the protocol, | ||||
so an example domain might be `https://cdn.phabcdn.net/`. | so an example domain might be `https://cdn.examplecdn.com/`. | ||||
phabricator/ $ ./bin/config set security.alternate-file-domain <domain> | phorge/ $ ./bin/config set security.alternate-file-domain <domain> | ||||
Phabricator should now serve CSS, JS, images, profile pictures, and user | Phorge should now serve CSS, JS, images, profile pictures, and user | ||||
content through the file domain. You can verify this with "View Source" or | content through the file domain. You can verify this with "View Source" or | ||||
by downloading a file and checking the URL. | by downloading a file and checking the URL. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0