[Summary view] [Print] [Text view]

   1  @title Configuring File Storage
   2  @group config
   3  
   4  Setup how Phabricator will store files.
   5  
   6  = Overview =
   7  
   8  Phabricator allows users to upload files, and several applications use file
   9  storage (for instance, Maniphest allows you to attach files to tasks). You can
  10  configure several different storage systems:
  11  
  12    - you can store data in MySQL: this is the easiest to set up, but doesn't
  13      scale well;
  14    - you can store data on local disk: this is also easy to set up but won't
  15      scale to multiple web frontends without NFS;
  16    - or you can build a custom storage engine.
  17  
  18  By default, Phabricator is configured to store files up to 1MB in MySQL, and
  19  reject files larger than 1MB. It is recommended you set up local disk storage
  20  for files larger than 1MB. This should be sufficient for most installs. If you
  21  have a larger install or more unique requirements, you may want to customize
  22  this further.
  23  
  24  For technical documentation (including instructions on building custom storage
  25  engines) see @{article:File Storage Technical Documentation}.
  26  
  27  You don't have to fully configure this immediately, the defaults are okay until
  28  you need to upload larger files and it's relatively easy to port files between
  29  storage engines later.
  30  
  31  = Storage Engines =
  32  
  33  Builtin storage engines and information on how to configure them.
  34  
  35  == MySQL ==
  36  
  37    - **Pros**: Fast, no setup required.
  38    - **Cons**: Storing files in a database is a classic bad idea. Does not scale
  39      well. Maximum file size is limited.
  40  
  41  MySQL storage is configured by default, for files up to (just under) 1MB. You
  42  can configure it with these keys:
  43  
  44    - ##storage.mysql-engine.max-size##: Change the filesize limit. Set to 0
  45      to disable.
  46  
  47  For most installs, it is recommended you configure local disk storage below,
  48  and then either leave this as is or disable it, depending on how upset you feel
  49  about putting files in a database.
  50  
  51  == Local Disk ==
  52  
  53    - **Pros**: Very simple. Almost no setup required.
  54    - **Cons**: Doesn't scale to multiple web frontends without NFS.
  55  
  56  For most installs, it is **strongly recommended** that you configure local disk
  57  storage. To do this, set the configuration key:
  58  
  59    - ##storage.local-disk.path##: Set to some writable directory on local disk.
  60      Make that directory. You're done.
  61  
  62  == Amazon S3 ==
  63  
  64    - **Pros**: Scales well.
  65    - **Cons**: More complicated and expensive than other approaches.
  66  
  67  To enable file storage in S3, set these key:
  68  
  69    - ##amazon-s3.access-key## Your AWS access key.
  70    - ##amazon-s3.secret-key## Your AWS secret key.
  71    - ##storage.s3.bucket## S3 bucket name where files should be stored.
  72  
  73  == Custom Engine ==
  74  
  75  For details about writing a custom storage engine, see @{article:File Storage
  76  Technical Documentation}.
  77  
  78  = Testing Storage Engines =
  79  
  80  You can test that things are correctly configured by going to the Files
  81  application (##/file/##) and uploading files.
  82  
  83  = Migrating Files Between Engines =
  84  
  85  If you want to move files between storage engines, you can use the `bin/files`
  86  script to perform migrations. For example, suppose you previously used MySQL but
  87  recently set up S3 and want to migrate all your files there. First, migrate one
  88  file to make sure things work:
  89  
  90    phabricator/ $ ./bin/files migrate --engine amazon-s3 F12345
  91  
  92  If that works properly, you can then migrate everything:
  93  
  94    phabricator/ $ ./bin/files migrate --engine amazon-s3 --all
  95  
  96  You can use `--dry-run` to show which migrations would be performed without
  97  taking any action. Run `bin/files help` for more options and information.
  98  
  99  = Next Steps =
 100  
 101  Continue by:
 102  
 103    - configuring file size upload limits with
 104      @{article:Configuring File Upload Limits}; or
 105    - returning to the @{article:Configuration Guide}.