Update README.md

This commit is contained in:
Marius 2018-02-16 23:17:13 +01:00 committed by GitHub
parent 755e892e30
commit cdafea14dc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 94 additions and 10 deletions

104
README.md
View File

@ -14,6 +14,11 @@ specifies a flexible method to upload files to remote servers using HTTP.
The special feature is the ability to pause and resume uploads at any
moment allowing to continue seamlessly after e.g. network interruptions.
It is capable of accepting uploads with arbitrary sizes and storing them locally
on disk, on Google Cloud Storage or on AWS S3 (or any other S3-compatible
storage system). Due to its modularization and extensibility, support for
nearly any other cloud provider could easily be added to tusd.
**Protocol version:** 1.0.0
## Getting started
@ -26,23 +31,102 @@ Windows in various formats of the
### Compile from source
**Requirements:**
* [Go](http://golang.org/doc/install) (1.5 or newer)
**Running tusd from source:**
Clone the git repository and `cd` into it.
The only requirement for building tusd is [Go](http://golang.org/doc/install) 1.5 or newer.
If you meet this criteria, you can clone the git repository and build the binary:
```bash
git clone git@github.com:tus/tusd.git
cd tusd
go build -o tusd cmd/tusd/main
```
Now you can run tusd:
## Running tusd
```bash
go run cmd/tusd/main.go
Start the tusd upload server is as simple as invoking a single command. For example, following
snippet demostrates how to start a tusd process which accepts tus uploads at
`http://localhost:1080/files/` and stores them locally in the `./data` directory:
```
$ tusd -dir ./data
[tusd] Using './data' as directory storage.
[tusd] Using 0.00MB as maximum size.
[tusd] Using 0.0.0.0:1080 as address to listen.
[tusd] Using /files/ as the base path.
[tusd] Using /metrics as the metrics path.
```
Alternatively, if you want to store the uploads on an AWS S3 bucket, you only have to specify
the bucket and provide the corresponding access credentials and region information using
environment variables (if you want to use a S3-compatible store, use can use the `-s3-endpoint`
option):
```
$ export AWS_ACCESS_KEY_ID=xxxxx
$ export AWS_SECRET_ACCESS_KEY=xxxxx
$ export AWS_REGION=eu-west-1
$ tusd -s3-bucket my-test-bucket.com
[tusd] Using 's3://my-test-bucket.com' as S3 bucket for storage.
[tusd] Using 0.00MB as maximum size.
[tusd] Using 0.0.0.0:1080 as address to listen.
[tusd] Using /files/ as the base path.
[tusd] Using /metrics as the metrics path.
```
Furthermore, tusd also has support for storing uploads on Google Cloud Storage. In order to
enable this feature, supply the path to your account file containing the necessary credentials:
```
$ export GCS_SERVICE_ACCOUNT_FILE=./account.json
$ tusd -gcs-bucket my-test-bucket.com
[tusd] Using 'gcs://my-test-bucket.com' as GCS bucket for storage.
[tusd] Using 0.00MB as maximum size.
[tusd] Using 0.0.0.0:1080 as address to listen.
[tusd] Using /files/ as the base path.
[tusd] Using /metrics as the metrics path.
```
Besides these simple examples, tusd can be easily configured using a variety of command line
options:
```
$ tusd -help
Usage of tusd:
-base-path string
Basepath of the HTTP server (default "/files/")
-behind-proxy
Respect X-Forwarded-* and similar headers which may be set by proxies
-dir string
Directory to store uploads in (default "./data")
-expose-metrics
Expose metrics about tusd usage (default true)
-gcs-bucket string
Use Google Cloud Storage with this bucket as storage backend (requires the GCS_SERVICE_ACCOUNT_FILE environment variable to be set)
-hooks-dir string
Directory to search for available hooks scripts
-hooks-http string
An HTTP endpoint to which hook events will be sent to
-hooks-http-backoff int
Number of seconds to wait before retrying each retry (default 1)
-hooks-http-retry int
Number of times to retry on a 500 or network timeout (default 3)
-host string
Host to bind HTTP server to (default "0.0.0.0")
-max-size int
Maximum size of a single upload in bytes
-metrics-path string
Path under which the metrics endpoint will be accessible (default "/metrics")
-port string
Port to bind HTTP server to (default "1080")
-s3-bucket string
Use AWS S3 with this bucket as storage backend (requires the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION environment variables to be set)
-s3-endpoint string
Endpoint to use S3 compatible implementations like minio (requires s3-bucket to be pass)
-store-size int
Size of space allowed for storage
-timeout int
Read timeout for connections in milliseconds. A zero value means that reads will not timeout (default 30000)
-version
Print tusd version information
```
## Using tusd manually