Move content from FAQ into docs

Author: Acconut

docs/_getting-started/configuration.md

@@ -100,9 +100,9 @@ When integrating tusd into an application, it is important to establish a commun
 
 ## Cross-Origin Resource Sharing (CORS)
 
-When tusd is used in a web application and the tusd server is reachable under a different origin (domain, scheme, or port) than the frontend itself, browsers put restrictions on cross-origin requests for security reasons. Using the [Cross-Origin Resource Sharing (CORS) mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), the server can instruct the browser to allow cross-origin requests.
+When tusd is used in a web application and the tusd server is reachable under a different origin (domain, scheme, or port) than the frontend itself, browsers put restrictions on cross-origin requests for security reasons. For example, your main application is running on `https://example.org` but your tusd server is hosted at `https://uploads.example.org`. In this case, the server needs to use the [Cross-Origin Resource Sharing (CORS) mechanism](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to signal the browser that it will accept requests from `https://example.org`.
 
-By default, tusd will allow cross-origin requests from any origin. All methods and header fields necessary for the tus protocol are allowed in these requests.
+To make your setup easier, tusd already includes the necessary CORS configuration to allow communication with tus clients. By default, tusd will allow cross-origin requests from any origin.
 
 If you want to restrict the origins or add additional header fields to the CORS configuration, utilize the `-cors-*` flags:
 
@@ -132,7 +132,13 @@ If you want tusd to be accessible via HTTPS, there are two options:
 
 1. Use a TLS-terminating reverse proxy, such as Nginx. The proxy is configured to accept HTTPS requests from the clients and forwards unencrypted HTTP requests to tusd. This approach is the most flexible and recommended approach as such proxies provide detailed configuration options for HTTPS and are well tested. Please see the [section on proxies](#proxies) for additional details when using tusd with proxies.
 
-2. Tusd itself provies basic TLS support for HTTPS connections. In contrast to dedicated TLS-terminating proxies, tusd provides less configuration options for tuning the TLS setup. However, the built-in HTTPS support is useful for development, testing and encrypting internal traffic. The HTTPS support which can be enabled by supplying a certificate and private key. Note that the certificate file must include the entire chain of certificates up to the CA certificate. The default configuration supports TLSv1.2 and TLSv1.3. It is possible to use only TLSv1.3 with `-tls-mode=tls13`. Alternately, it is possible to disable TLSv1.3 and use only 256-bit AES ciphersuites with `-tls-mode=tls12-strong`. The following example generates a self-signed certificate for `localhost` and then uses it to serve files on the loopback address. Such a self-signed certificate is not appropriate for production use. Note also that the key file must not be encrypted/require a passphrase.
+2. Tusd itself provides basic TLS support for HTTPS connections. In contrast to dedicated TLS-terminating proxies, tusd supports less configuration options for tuning the TLS setup.
+However, the built-in HTTPS support is useful for development, testing and encrypting internal traffic. It can be enabled by supplying a certificate and private key. Note that the certificate file must include the entire chain of certificates up to the CA certificate and that the key file must not be encrypted/require a passphrase. The available modes are:
+- TLSv1.3+TLSv1.2 with support cipher suites per the guidelines on [Mozilla's SSL Configuration Generator](https://ssl-config.mozilla.org/#server=go&version=1.14.4&config=intermediate&guideline=5.6) (`-tls-mode=tls12`, the default mode)
+- TLSv1.2 with 256-bit AES ciphers only (`-tls-mode=tls12-strong`)
+- TLSv1.3-only (`-tls-mode=tls13`)
+
+The following example generates a self-signed certificate for `localhost` and then uses it to serve files on the loopback address. Such a self-signed certificate is not appropriate for production use.
 
 ```bash
 # Generate self-signed certificate

docs/_getting-started/installation.md

@@ -43,9 +43,23 @@ Each release of tusd is also published as a Docker image on Docker Hub. You can
 
 ```bash
 docker pull tusproject/tusd:latest
-docker run tusproject/tusd:latest # append CLI flags for tusd here
+docker run tusproject/tusd:latest # append CLI flags for tusd here, for example:
+# docker run tusproject/tusd:latest -s3-bucket=my-bucket
 ```
 
+### Using Docker Secrets for credentials (Swarm mode only)
+{: .no_toc }
+
+Example usage with credentials for the S3-compatible Minio service. Create the secrets:
+
+```bash
+printf "minio" | docker secret create minio-username -
+printf "miniosecret" | docker secret create minio-password -
+```
+
+Those commands create two secrets which are used inside the example [docker-compose.yml](https://github.com/tus/tusd/blob/main/examples/docker-compose.yml) file. The provided example assumes, that you also have a service named `minio` inside the same Docker Network.
+We just append a `_FILE` suffix to the corresponding environment variables. The contents of the mounted file will be added to the environment variable without `_FILE` suffix.
+
 ## Kubernetes installation
 
 A Helm chart for installing tusd on Kubernetes is available [here](https://github.com/sagikazarmark/helm-charts/tree/master/charts/tusd).

docs/faq.md

@@ -15,9 +15,7 @@ nav_order: 2
 
 ### How can I access tusd using HTTPS?
 
-Enable HTTPS by using the `-tls-certificate` and `-tls-key` flags. Note that the support for HTTPS is limited to a small subset of the many possible TLS configuration options. Available options are TLSv1.3-only; TLSv1.3+TLSv1.2 with support cipher suites per the guidelines on [Mozilla's SSL Configuration Generator](https://ssl-config.mozilla.org/#server=go&version=1.14.4&config=intermediate&guideline=5.6); and TLSv1.2 with 256-bit AES ciphers only. Also note that the key file must not be encrypted/require a passphrase.
-
-If your needs are more complex than provided for here, you will need to use a reverse proxy in front of tusd. This includes further fine-tuning of ciphers, and the addition of things like HSTS headers. More information about this topic, including sample configurations for Nginx and Apache, can be found in [issue #86](https://github.com/tus/tusd/issues/86#issuecomment-269569077) and in the [Apache example configuration](/examples/apache2.conf); rationale for why HTTPS is supported at all can be found in [issue #418](https://github.com/tus/tusd/issues/418).
+Yes, you can achieve this by either running tusd behind a TLS-terminating proxy (such as Nginx or Apache) or configuring tusd to serve HTTPS directly. Details on both approaches are given in the [configuration guide](/getting-started/configuration/#httpstls).
 
 ### Can I run tusd behind a reverse proxy?
 
@@ -27,52 +25,18 @@ Yes, it is absolutely possible to do so. Please consult the [section about confi
 
 Yes, this is made possible by the [hook system](/docs/hooks.md) inside the tusd binary. It enables custom routines to be executed when certain events occurs, such as a new upload being created which can be handled by the `pre-create` hook. Inside the corresponding hook file, you can run your own validations against the provided upload metadata to determine whether the action is actually allowed or should be rejected by tusd. Please have a look at the [corresponding documentation](/docs/hooks.md#pre-create) for a more detailed explanation.
 
-### Can I run tusd inside a VM/Vagrant/VirtualBox?
-
-Yes, you can absolutely do so without any modifications. However, there is one known problem: If you are using tusd inside VirtualBox (the default provider for Vagrant) and are storing the files inside a shared/synced folder, you might get TemporaryErrors (Lockfile created, but doesn't exist) when trying to upload. This happens because shared folders do not support hard links which are necessary for tusd. Please use another non-shared folder for storing files (see https://github.com/tus/tusd/issues/201).
-
 ### I am getting TemporaryErrors (Lockfile created, but doesn't exist)! What can I do?
 
-This error can occur when you are running tusd's disk storage on a file system which does not support hard links. These hard links are used to create lock files for ensuring that an upload's data is consistent. For example, this problem can happen when running tusd inside VirtualBox (see the answer above for more details) or when using file system interfaces to cloud storage providers (see https://github.com/tus/tusd/issues/257). We recommend you to ensure that your file system supports hard links, use a different file system, or use one of tusd's cloud storage abilities. If the problem still persists, please open a bug report.
+This error can occur when you are running tusd's disk storage on a file system which does not support hard links. Please consult the [local disk storage documentation](/storage-backends/local-disk/#issues-with-nfs-and-shared-folders) for more details.
 
 ### How can I prevent users from downloading the uploaded files?
 
-tusd allows any user to retrieve a previously uploaded file by issuing a HTTP GET request to the corresponding upload URL. This is possible as long as the uploaded files on the datastore have not been deleted or moved to another location. While it is a handy feature for debugging and testing your setup, we know that there are situations where you don't want to allow downloads or where you want more control about who downloads what. In these scenarios we recommend to place a proxy in front of tusd which takes on the task of access control or even preventing HTTP GET requests entirely. tusd has no feature built in for controling or disabling downloads on its own because the main focus is on accepting uploads, not serving files.
+Tusd allows any user to retrieve a previously uploaded file by issuing a HTTP GET request to the corresponding upload URL. This is possible as long as the uploaded files on the datastore have not been deleted or moved to another location. This can be completely disabled using the [`-disable-download` flag](/getting-started/configuration/#disable-downloads).
 
 ### How can I keep the original filename for the uploads?
 
 tusd will generate a unique ID for every upload, e.g. `1881febb4343e9b806cad2e676989c0d`, which is also used as the filename for storing the upload. If you want to keep the original filename, e.g. `my_image.png`, you will have to rename the uploaded file manually after the upload is completed. One can use the [`post-finish` hook](https://github.com/tus/tusd/blob/main/docs/hooks.md#post-finish) to be notified once the upload is completed. The client must also be configured to add the filename to the upload's metadata, which can be [accessed inside the hooks](https://github.com/tus/tusd/blob/main/docs/hooks.md#the-hooks-environment) and used for the renaming operation.
 
 ### Does tusd support Cross-Origin Resource Sharing (CORS)?
 
-[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) is a technique to allow sharing of data between websites, which are hosted on different origins/domains. This is a common task with tus where you have your main application running on `https://example.org` but your tus server is hosted at `https://uploads.example.org`. In this case, the tus server needs to support CORS to signal the browser that it will accept requests from `https://example.org`.
-
-To make your setup easier, tusd already includes the necessary CORS configuration to allow communication with tus clients. By default, it will allow incoming requests from any origin. Following headers are allowed to be included into HTTP requests:
-
- * `Authorization`: Defined in [RFC 2617](https://tools.ietf.org/html/rfc2617#section-2), used in various HTTP authentication protocols.
- * `Origin`: Defined in [RFC 6454](https://tools.ietf.org/html/rfc6454), used to specify the origin of a HTTP request. This header is often used to aid in HTTP security.
- * `X-Requested-With`: Used to identify AJAX requests. See [here](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) for details.
- * `X-Request-ID`: Correlates HTTP requests between a client and server. See [here](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) for details.
- * `X-HTTP-Method-Override`: Requests a web application to override the method specified in the request with the method given in the header field. See [here](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields) for details.
- * `Content-Type`: Defined in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.17), indicates the media type of the entity-body.
- * `Upload-Length`: A tus specific header used to indicate the total size of an uploaded file. See [here](https://tus.io/protocols/resumable-upload.html#upload-length) for details.
- * `Upload-Offset`: A tus specific header used to indicate the starting byte that a PATCH should be used on to upload a chunk of a file. See [here](https://tus.io/protocols/resumable-upload.html#upload-offset) for details.
- * `Tus-Resumable`: A tus specific header used to match the client version with the server version of the tus protocol. See [here](https://tus.io/protocols/resumable-upload.html#tus-resumable) for details.
- * `Upload-Metadata`: A tus specific header used for integrators to communicate general metadata between a client and server. See [here](https://tus.io/protocols/resumable-upload.html#upload-metadata) for details.
- * `Upload-Defer-Length`: A tus specific header used to communicate if the upload file size is not known during the HTTP request it is in. See [here](https://tus.io/protocols/resumable-upload.html#upload-defer-length) for details.
- * `Upload-Concat`: A tus specific header used to indicate if the containing HTTP request is the final request for uploading a file or not. See [here](https://tus.io/protocols/resumable-upload.html#upload-concat) for details.
-
-If you are looking for a way to communicate additional information from a client to a server, use the `Upload-Metadata` header.
-
-### How to use Docker Secrets for credentials (Swarm mode only)
-
-Example usage with "minio"/S3 (AWS). Create the secrets:
-
-```bash
-printf "minio" | docker secret create minio-username -
-printf "miniosecret" | docker secret create minio-password -
-```
-
-Those commands create two secrets which are used inside the example [docker-compose.yml](../examples/docker-compose.yml) file.
-The provided example assumes, that you also have a service named "minio" inside the same Docker Network.
-We just append a _FILE suffix to the corresponding environment variables. The contents of the mounted file will be added to the environment variable without _FILE suffix.
+Yes, tusd does have built-in support for CORS, which can be [fully customized](/getting-started/configuration/#cross-origin-resource-sharing-cors).