536b0867de
Summary: Ref T988. I'm splitting the Phabricator documentation into two separate documentation books, one less technical and one more technical. Move all the `.diviner` article files around into `src/docs/user/` or `src/docs/tech/`, accordingly. The only actual changes here are a couple of config changes in the `.book` files. Test Plan: Regenerated user and technical documentation and saw stuff in the right places. Reviewers: btrahan Reviewed By: btrahan CC: chad, aran Maniphest Tasks: T988 Differential Revision: https://secure.phabricator.com/D6822
106 lines
3.6 KiB
Plaintext
106 lines
3.6 KiB
Plaintext
@title Configuring File Storage
|
|
@group config
|
|
|
|
Setup how Phabricator will store files.
|
|
|
|
= Overview =
|
|
|
|
Phabricator allows users to upload files, and several applications use file
|
|
storage (for instance, Maniphest allows you to attach files to tasks). You can
|
|
configure several different storage systems:
|
|
|
|
- you can store data in MySQL: this is the easiest to set up, but doesn't
|
|
scale well;
|
|
- you can store data on local disk: this is also easy to set up but won't
|
|
scale to multiple web frontends without NFS;
|
|
- or you can build a custom storage engine.
|
|
|
|
By default, Phabricator is configured to store files up to 1MB in MySQL, and
|
|
reject files larger than 1MB. It is recommended you set up local disk storage
|
|
for files larger than 1MB. This should be sufficient for most installs. If you
|
|
have a larger install or more unique requirements, you may want to customize
|
|
this further.
|
|
|
|
For technical documentation (including instructions on building custom storage
|
|
engines) see @{article:File Storage Technical Documentation}.
|
|
|
|
You don't have to fully configure this immediately, the defaults are okay until
|
|
you need to upload larger files and it's relatively easy to port files between
|
|
storage engines later.
|
|
|
|
= Storage Engines =
|
|
|
|
Builtin storage engines and information on how to configure them.
|
|
|
|
== MySQL ==
|
|
|
|
- **Pros**: Fast, no setup required.
|
|
- **Cons**: Storing files in a database is a classic bad idea. Does not scale
|
|
well. Maximum file size is limited.
|
|
|
|
MySQL storage is configured by default, for files up to (just under) 1MB. You
|
|
can configure it with these keys:
|
|
|
|
- ##storage.mysql-engine.max-size##: Change the filesize limit. Set to 0
|
|
to disable.
|
|
|
|
For most installs, it is recommended you configure local disk storage below,
|
|
and then either leave this as is or disable it, depending on how upset you feel
|
|
about putting files in a database.
|
|
|
|
== Local Disk ==
|
|
|
|
- **Pros**: Very simple. Almost no setup required.
|
|
- **Cons**: Doesn't scale to multiple web frontends without NFS.
|
|
|
|
For most installs, it is **strongly recommended** that you configure local disk
|
|
storage. To do this, set the configuration key:
|
|
|
|
- ##storage.local-disk.path##: Set to some writable directory on local disk.
|
|
Make that directory. You're done.
|
|
|
|
== Amazon S3 ==
|
|
|
|
- **Pros**: Scales well.
|
|
- **Cons**: More complicated and expensive than other approaches.
|
|
|
|
To enable file storage in S3, set these key:
|
|
|
|
- ##amazon-s3.access-key## Your AWS access key.
|
|
- ##amazon-s3.secret-key## Your AWS secret key.
|
|
- ##storage.s3.bucket## S3 bucket name where files should be stored.
|
|
|
|
== Custom Engine ==
|
|
|
|
For details about writing a custom storage engine, see @{article:File Storage
|
|
Technical Documentation}.
|
|
|
|
= Testing Storage Engines =
|
|
|
|
You can test that things are correctly configured by going to the Files
|
|
application (##/file/##) and uploading files.
|
|
|
|
= Migrating Files Between Engines =
|
|
|
|
If you want to move files between storage engines, you can use the `bin/files`
|
|
script to perform migrations. For example, suppose you previously used MySQL but
|
|
recently set up S3 and want to migrate all your files there. First, migrate one
|
|
file to make sure things work:
|
|
|
|
phabricator/ $ ./bin/files migrate --engine amazon-s3 F12345
|
|
|
|
If that works properly, you can then migrate everything:
|
|
|
|
phabricator/ $ ./bin/files migrate --engine amazon-s3 --all
|
|
|
|
You can use `--dry-run` to show which migrations would be performed without
|
|
taking any action. Run `bin/files help` for more options and information.
|
|
|
|
= Next Steps =
|
|
|
|
Continue by:
|
|
|
|
- configuring file size upload limits with
|
|
@{article:Configuring File Upload Limits}; or
|
|
- returning to the @{article:Configuration Guide}.
|