diff --git a/docs/_advanced-topics/hooks.md b/docs/_advanced-topics/hooks.md index 5ceabb20..84db84b1 100644 --- a/docs/_advanced-topics/hooks.md +++ b/docs/_advanced-topics/hooks.md @@ -222,7 +222,7 @@ When the process exits with the zero exit code, tusd reads the process' stdout a The process' stderr is redirected to tusd's stderr and can be used for logging from inside the hook. -An example is available at [/examples/hooks/file](/examples/hooks/file). +An example is available at [/examples/hooks/file]({{ site.baseurl }}/examples/hooks/file). ### HTTP(S) Hooks @@ -250,7 +250,7 @@ When the endpoint responds with a non-2XX status code, tusd interprets this as a When the endpoint responds with a 2XX status code, tusd reads the response body and parses it as a JSON-encoded hook response. This allows the hook to customize the HTTP response, reject and abort uploads. -An example is available at [/examples/hooks/http](/examples/hooks/http). +An example is available at [/examples/hooks/http]({{ site.baseurl }}/examples/hooks/http). #### Retries @@ -273,7 +273,7 @@ $ tusd -hooks-grpc localhost:8081 ... ``` -The endpoint must implement the hook handler service as specified in [/pkg/hooks/grpc/proto/hook.proto](/pkg/hooks/grpc/proto/hook.proto). Its `InvokeHook` method will be invoked for each triggered events and will be passed the hook request. +The endpoint must implement the hook handler service as specified in [/pkg/hooks/grpc/proto/hook.proto]({{ site.baseurl }}/pkg/hooks/grpc/proto/hook.proto). Its `InvokeHook` method will be invoked for each triggered events and will be passed the hook request. #### Retries @@ -290,7 +290,7 @@ File hooks are an easy way to receive events from tusd, but can induce overhead Plugin hooks provide a sweet spot between these two worlds. You can create a plugin with any programming language. tusd then loads this plugin by starting it as a standalone process, restarting it if necessary, and communicating with it over local sockets. This system is powered by [go-plugin](https://github.com/hashicorp/go-plugin), which is designed for Go, but provides cross-language support. The approach provides a low-overhead hook handler, which is still able to track state between hooks. -To learn more, have a look at the example at [/examples/hooks/plugin](/examples/hooks/plugin). +To learn more, have a look at the example at [/examples/hooks/plugin]({{ site.baseurl }}/examples/hooks/plugin). ## Common Uses diff --git a/docs/_config.yml b/docs/_config.yml index 4a853145..4b0088e4 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -2,7 +2,8 @@ title: tusd documentation description: Reference server implementation in Go of tus, the open protocol for resumable file uploads. theme: just-the-docs -url: https://just-the-docs.github.io +url: https://tus.github.io +baseurl: /tusd # Custom color scheme from _sass/color_schemes/custom.scss color_scheme: custom diff --git a/docs/_getting-started/configuration.md b/docs/_getting-started/configuration.md index c08e711f..dcb8ff83 100644 --- a/docs/_getting-started/configuration.md +++ b/docs/_getting-started/configuration.md @@ -92,11 +92,11 @@ $ tusd -disable-termination ## Storage backend -Tusd has been designed with flexible storage backends in mind and can store the received uploads on local disk or various cloud provides (AWS S3, Azure Cloud Storage, and Google Cloud Storage). By default, tusd will store uploads in the directory specified by the `-upload-dir` flag (which defaults to `./data`). Please consult the dedicated [Storage Backends section](/storage-backends/overview/) for details on how to use different storage backend and configure them. +Tusd has been designed with flexible storage backends in mind and can store the received uploads on local disk or various cloud provides (AWS S3, Azure Cloud Storage, and Google Cloud Storage). By default, tusd will store uploads in the directory specified by the `-upload-dir` flag (which defaults to `./data`). Please consult the dedicated [Storage Backends section]({{ site.baseurl }}/storage-backends/overview/) for details on how to use different storage backend and configure them. ## Integrations into applications with hooks -When integrating tusd into an application, it is important to establish a communication channel between tusd and your main application. For this purpose, tusd provides a hook system which triggers user-defined actions when certain events happen, for example when an upload is created or finished. This simple-but-powerful system enables many uses, such as logging, validation, authorization, and post-processing of the uploaded files. Please consult the dedicated [Storage Backends section](/advanced-topics/hooks/) for details on how to use the hook system. +When integrating tusd into an application, it is important to establish a communication channel between tusd and your main application. For this purpose, tusd provides a hook system which triggers user-defined actions when certain events happen, for example when an upload is created or finished. This simple-but-powerful system enables many uses, such as logging, validation, authorization, and post-processing of the uploaded files. Please consult the dedicated [Storage Backends section]({{ site.baseurl }}/advanced-topics/hooks/) for details on how to use the hook system. ## Cross-Origin Resource Sharing (CORS) diff --git a/docs/_getting-started/usage.md b/docs/_getting-started/usage.md index 082451b9..d31432d7 100644 --- a/docs/_getting-started/usage.md +++ b/docs/_getting-started/usage.md @@ -31,12 +31,12 @@ The last line from tusd's output indicates the *upload creation URL*: You can now upload files to: http://[::]:8080/files/ ``` -This URL can be used by clients to create new uploads. If you want to customize its host, port, or base path, please use the [Network configuration options](/getting-started/configuration/#network-configuration). +This URL can be used by clients to create new uploads. If you want to customize its host, port, or base path, please use the [Network configuration options]({{ site.baseurl }}/getting-started/configuration/#network-configuration). {: .note } The `[::]` section in the URL indicates that tusd is accepting connections on all network interfaces, including IPv6. If the client and tusd are on running on the same machine, it can be replaced with `localhost` to form a URL, such as `http://localhost:8080/files/`. -Uploaded files will be stored by default in the directory specified with the `-upload-dir` options. It defaults to the `data` directory in the current working directory. Alternatively, tusd can also store uploads directly on various cloud storage services. Please consult the [Storage Backends section](/storage-backends/overview/) for more details. +Uploaded files will be stored by default in the directory specified with the `-upload-dir` options. It defaults to the `data` directory in the current working directory. Alternatively, tusd can also store uploads directly on various cloud storage services. Please consult the [Storage Backends section]({{ site.baseurl }}/storage-backends/overview/) for more details. # Connecting clients diff --git a/docs/_storage-backends/aws-s3.md b/docs/_storage-backends/aws-s3.md index 84cbef4b..dd088448 100644 --- a/docs/_storage-backends/aws-s3.md +++ b/docs/_storage-backends/aws-s3.md @@ -68,7 +68,7 @@ s3:PutObject Uploads on S3 are stored using multiple objects: -- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends](/storage-backends/overview/#storage-format). +- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends]({{ site.baseurl }}/storage-backends/overview/#storage-format). - An [S3 multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) is used to transfer the file piece-by-piece to S3 and reassemble the original file once the upload is finished. It is removed once the upload is finished. - A file object will contain the uploaded file. It will only be created once the entire upload is finished. - A temporary object with the `.part` extension may be created when the upload has been paused to store some temporary data which cannot be transferred to the S3 multipart upload due to its small size. Once the upload is resumed, the temporary object will be gone. diff --git a/docs/_storage-backends/azure-blob-storage.md b/docs/_storage-backends/azure-blob-storage.md index ddc4c217..95a43bed 100644 --- a/docs/_storage-backends/azure-blob-storage.md +++ b/docs/_storage-backends/azure-blob-storage.md @@ -51,7 +51,7 @@ $ tusd -azure-storage=my-test-container -azure-blob-access-tier=cool Uploads are stored using multiple objects: -- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends](/storage-backends/overview/#storage-format). +- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends]({{ site.baseurl }}/storage-backends/overview/#storage-format). - A file object will contain the uploaded file. Data is appended to the object while the upload is performed. By default, the objects are stored at the root of the container. For example the objects for the upload ID `abcdef123` will be: diff --git a/docs/_storage-backends/google-cloud-storage.md b/docs/_storage-backends/google-cloud-storage.md index 23cb28b5..34cf5e29 100644 --- a/docs/_storage-backends/google-cloud-storage.md +++ b/docs/_storage-backends/google-cloud-storage.md @@ -35,7 +35,7 @@ The used service account must have the `https://www.googleapis.com/auth/devstora Uploads are stored using multiple objects: -- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends](/storage-backends/overview/#storage-format). +- An informational object with the `.info` extension holds meta information about the uploads, as described in [the section for all storage backends]({{ site.baseurl }}/storage-backends/overview/#storage-format). - A file object will contain the uploaded file. Data is appended to the object while the upload is performed. By default, the objects are stored at the root of the bucket. For example the objects for the upload ID `abcdef123` will be: diff --git a/docs/_storage-backends/local-disk.md b/docs/_storage-backends/local-disk.md index cdb956c5..aa65b0ff 100644 --- a/docs/_storage-backends/local-disk.md +++ b/docs/_storage-backends/local-disk.md @@ -15,11 +15,11 @@ $ tusd -upload-dir=./uploads When a new upload is created, for example with the upload ID `abcdef123`, tusd creates two files: - `./uploads/abcdef123` to hold the file content that is uploaded -- `./uploads/abcdef123.info` to hold [meta information about the upload](/storage-backends/overview/#storage-format) +- `./uploads/abcdef123.info` to hold [meta information about the upload]({{ site.baseurl }}/storage-backends/overview/#storage-format) ## Issues with NFS and shared folders -Tusd maintains [upload locks](/advanced-topics/locks/) on disk to ensure exclusive access to uploads and prevent data corruption. These disk-based locks utilize hard links, which might not supported by older NFS versions or when a folder is shared in a VM using VirtualBox or Vagrant. In these cases, you might get errors like this: +Tusd maintains [upload locks]({{ site.baseurl }}/advanced-topics/locks/) on disk to ensure exclusive access to uploads and prevent data corruption. These disk-based locks utilize hard links, which might not supported by older NFS versions or when a folder is shared in a VM using VirtualBox or Vagrant. In these cases, you might get errors like this: ``` TemporaryErrors (Lockfile created, but doesn't exist) diff --git a/docs/_storage-backends/overview.md b/docs/_storage-backends/overview.md index f0b527dc..ea2f4dba 100644 --- a/docs/_storage-backends/overview.md +++ b/docs/_storage-backends/overview.md @@ -8,17 +8,17 @@ nav_order: 1 Tusd can store the uploaded files either on local disk or various cloud storage services: -- [Local disk](/storage-backends/local-disk/) -- [AWS S3 (and S3-compatible services)](/storage-backends/aws-s3/) -- [Azure Blob Storage](/storage-backends/azure-blob-storage/) -- [Google Cloud Storage](/storage-backends/google-cloud-storage/) +- [Local disk]({{ site.baseurl }}/storage-backends/local-disk/) +- [AWS S3 (and S3-compatible services)]({{ site.baseurl }}/storage-backends/aws-s3/) +- [Azure Blob Storage]({{ site.baseurl }}/storage-backends/azure-blob-storage/) +- [Google Cloud Storage]({{ site.baseurl }}/storage-backends/google-cloud-storage/) ## Storage format While the exact details of how uploaded files are stored depend on the chosen backend, usually two files/objects are created and modified while the upload is progressing: - An informational file/object with the `.info` extension holds meta information about the upload, such as its size, its metadata, and whether it is used in conjunction with the [concatenation extension](https://tus.io/protocols/resumable-upload#concatenation). The data encoded using [JSON](https://www.json.org/json-en.html). More details can be found in the [documentation of the underlying data structure](https://pkg.go.dev/github.com/tus/tusd@v1.13.0/pkg/handler#FileInfo). -- Another file/object is created to store the actual file data. It does not have a characteristic extension and its name is either set by the [pre-create hook](/advanced-topics/hooks/) or chosen by the storage backend. Once the upload is finished, it will contain the entire uploaded data. Please note depending on the storage backend (e.g. S3), this file/object might not be present until all data has been transferred. +- Another file/object is created to store the actual file data. It does not have a characteristic extension and its name is either set by the [pre-create hook]({{ site.baseurl }}/advanced-topics/hooks/) or chosen by the storage backend. Once the upload is finished, it will contain the entire uploaded data. Please note depending on the storage backend (e.g. S3), this file/object might not be present until all data has been transferred. Once an upload is finished, both files/objects are preserved for further processing depending on your application's needs. The informational file/object is useful to retrieve upload metadata and thus not automatically removed by tusd. @@ -28,4 +28,4 @@ In a multi-storage setup, multiple storage backends could be configured and dyna Unfortunately, tusd currently does not support multi-storage setups well. When tusd is started, it will load the configured storage backend, but is not able to dynamically switch between other storage backends. -If you are [using tusd programmatically as a package inside your Go application](/advanced-topics/usage-package/), you can overcome this limitation by dynamically creating multiple tusd handler with different storage backends. Once a request comes in, you need to determine the correct tusd handler for processing and can then route the request accordingly. +If you are [using tusd programmatically as a package inside your Go application]({{ site.baseurl }}/advanced-topics/usage-package/), you can overcome this limitation by dynamically creating multiple tusd handler with different storage backends. Once a request comes in, you need to determine the correct tusd handler for processing and can then route the request accordingly. diff --git a/docs/faq.md b/docs/faq.md index 5820b9cf..5764fd71 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -15,23 +15,23 @@ nav_order: 2 ### How can I access tusd using HTTPS? -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). +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]({{ site.baseurl }}/getting-started/configuration/#httpstls). ### Can I run tusd behind a reverse proxy? -Yes, it is absolutely possible to do so. Please consult the [section about configuration regarding proxies](/getting-started/configuration/#proxies). +Yes, it is absolutely possible to do so. Please consult the [section about configuration regarding proxies]({{ site.baseurl }}/getting-started/configuration/#proxies). ### Can I run custom verification/authentication checks before an upload begins? -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. +Yes, this is made possible by the [hook system]({{ site.baseurl }}/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]({{ site.baseurl }}/docs/hooks.md#pre-create) for a more detailed explanation. ### 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. Please consult the [local disk storage documentation](/storage-backends/local-disk/#issues-with-nfs-and-shared-folders) for more details. +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]({{ site.baseurl }}/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. This can be completely disabled using the [`-disable-download` flag](/getting-started/configuration/#disable-downloads). +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]({{ site.baseurl }}/getting-started/configuration/#disable-downloads). ### How can I keep the original filename for the uploads? @@ -39,4 +39,4 @@ tusd will generate a unique ID for every upload, e.g. `1881febb4343e9b806cad2e67 ### Does tusd support Cross-Origin Resource Sharing (CORS)? -Yes, tusd does have built-in support for CORS, which can be [fully customized](/getting-started/configuration/#cross-origin-resource-sharing-cors). +Yes, tusd does have built-in support for CORS, which can be [fully customized]({{ site.baseurl }}/getting-started/configuration/#cross-origin-resource-sharing-cors). diff --git a/docs/index.md b/docs/index.md index 77fe81cb..a2ed5184 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,26 +18,26 @@ protocol](http://www.tus.io/protocols/resumable-upload.html): ## Highlights - Multiple storage options: - - [Local disk](/storage-backends/local-disk/) - - [AWS S3](/storage-backends/aws-s3/) - - [Azure Blob Storage](/storage-backends/azure-blob-storage/) - - [Google Cloud Storage](/storage-backends/google-cloud-storage/) -- Fully customize using [hook system](/advanced-topics/hooks/) via [scripts](/advanced-topics/hooks/#file-hooks), [HTTP requests](/advanced-topics/hooks/#https-hooks), or [gRPC](/advanced-topics/hooks/#grpc-hooks): - - [Upload validation](/advanced-topics/hooks/#receiving-and-validating-user-data) - - [User authentication and authorization](/advanced-topics/hooks/#authenticating-users) - - [File post-processing](/advanced-topics/hooks/#post-processing-files) + - [Local disk]({{ site.baseurl }}/storage-backends/local-disk/) + - [AWS S3]({{ site.baseurl }}/storage-backends/aws-s3/) + - [Azure Blob Storage]({{ site.baseurl }}/storage-backends/azure-blob-storage/) + - [Google Cloud Storage]({{ site.baseurl }}/storage-backends/google-cloud-storage/) +- Fully customize using [hook system]({{ site.baseurl }}/advanced-topics/hooks/) via [scripts]({{ site.baseurl }}/advanced-topics/hooks/#file-hooks), [HTTP requests]({{ site.baseurl }}/advanced-topics/hooks/#https-hooks), or [gRPC]({{ site.baseurl }}/advanced-topics/hooks/#grpc-hooks): + - [Upload validation]({{ site.baseurl }}/advanced-topics/hooks/#receiving-and-validating-user-data) + - [User authentication and authorization]({{ site.baseurl }}/advanced-topics/hooks/#authenticating-users) + - [File post-processing]({{ site.baseurl }}/advanced-topics/hooks/#post-processing-files) - Supports arbitrarily large files - Can receive uploads from any [tus-compatible client](https://tus.io/implementations) -- Distributed as a [single binary without needing a runtime](/getting-started/installation/#download-pre-builts-binaries-recommended) -- Easily [embedded in Go applications](/advanced-topics/usage-package/) +- Distributed as a [single binary without needing a runtime]({{ site.baseurl }}/getting-started/installation/#download-pre-builts-binaries-recommended) +- Easily [embedded in Go applications]({{ site.baseurl }}/advanced-topics/usage-package/) ## Getting Started -To get started, have a look at the available [installation methods](/getting-started/installation/) for tusd. Once that's done, you can check out the [usage guide](/getting-started/usage/) to get tusd running and connect clients to it. Further details are available in the [configuration section](/getting-started/configuration/) and the [storage overview](/storage-backends/overview/). +To get started, have a look at the available [installation methods]({{ site.baseurl }}/getting-started/installation/) for tusd. Once that's done, you can check out the [usage guide]({{ site.baseurl }}/getting-started/usage/) to get tusd running and connect clients to it. Further details are available in the [configuration section]({{ site.baseurl }}/getting-started/configuration/) and the [storage overview]({{ site.baseurl }}/storage-backends/overview/). ## Help -If you have questions or problem, please read the [frequently asked questions](/faq.html). If these didn't cover your issue, feel free to ask us in the [GitHub repository](https://github.com/tus/tusd) or in our [community forum](https://community.transloadit.com/c/tus/6). If you wish for private consulting, Transloadit offers [commercial support for tus](https://transloadit.com/open-source/support/). +If you have questions or problem, please read the [frequently asked questions]({{ site.baseurl }}/faq.html). If these didn't cover your issue, feel free to ask us in the [GitHub repository](https://github.com/tus/tusd) or in our [community forum](https://community.transloadit.com/c/tus/6). If you wish for private consulting, Transloadit offers [commercial support for tus](https://transloadit.com/open-source/support/). ## License