From e2a65a5b62a42f94d985ca7ffa3fa5e0d3673199 Mon Sep 17 00:00:00 2001 From: Andrei Marcu Date: Thu, 14 May 2020 00:51:19 -0700 Subject: [PATCH] README: Clarify docker usage and example --- .gitignore | 1 + README.md | 81 ++++++++++++++++++++++------------------ linx-server.conf.example | 12 ++++++ 3 files changed, 57 insertions(+), 37 deletions(-) create mode 100644 linx-server.conf.example diff --git a/.gitignore b/.gitignore index ec613f1..df2bae9 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,7 @@ _testmain.go linx-server linx-cleanup/linx-cleanup linx-genkey/linx-genkey +linx-server.conf files/ meta/ binaries/ diff --git a/README.md b/README.md index 567d646..d509689 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,14 @@ Getting started ------------------- #### Using Docker +1. Create directories ```files``` and ```meta``` and run ```chown -R 65534:65534 meta && chown -R 65534:65534 files``` +2. Create a config file (example provided in repo), we'll refer to it as __linx-server.conf__ in the following examples + + + Example running ``` -docker run -p 8080:8080 -v /path/to/meta:/data/meta -v /path/to/files:/data/files andreimarcu/linx-server +docker run -p 8080:8080 -v /path/to/linx-server.conf:/data/linx-server.conf -v /path/to/meta:/data/meta -v /path/to/files:/data/files andreimarcu/linx-server -config /data/linx-server.conf ``` Example with docker-compose @@ -40,11 +45,12 @@ services: linx-server: container_name: linx-server image: andreimarcu/linx-server - entrypoint: /usr/local/bin/linx-server -bind=0.0.0.0:8080 -filespath=/data/files/ -metapath=/data/meta/ - command: -sitename=Linx -siteurl=https://linx.example.com + entrypoint: /usr/local/bin/linx-server + command: -config /data/linx-server.conf volumes: - /path/to/files:/data/files - /path/to/meta:/data/meta + - /path/to/linx-server.conf:/data/linx-server.conf network_mode: bridge ports: - "8080:8080" @@ -57,40 +63,41 @@ Ideally, you would use a reverse proxy such as nginx or caddy to handle TLS cert 1. Grab the latest binary from the [releases](https://github.com/andreimarcu/linx-server/releases) 2. Run ```./linx-server``` - Usage ----- #### Configuration -All configuration options are accepted either as arguments or can be placed in an ini-style file as such: +All configuration options are accepted either as arguments or can be placed in a file as such (see example file linx-server.conf.example in repo): ```ini +bind = 127.0.0.1:8080 +sitename = myLinx maxsize = 4294967296 -allowhotlink = true -# etc -``` -...and then invoke ```linx-server -config path/to/config.ini``` +maxexpiry = 86400 +# ... etc +``` +...and then run ```linx-server -config path/to/linx-server.conf``` #### Options |Option|Description |------|----------- -| ```-bind 127.0.0.1:8080``` | what to bind to (default is 127.0.0.1:8080) -| ```-sitename myLinx``` | the site name displayed on top (default is inferred from Host header) -| ```-siteurl "https://mylinx.example.org/"``` | the site url (default is inferred from execution context) -| ```-selifpath "selif"``` | path relative to site base url (the "selif" in mylinx.example.org/selif/image.jpg) where files are accessed directly (default: selif) -| ```-maxsize 4294967296``` | maximum upload file size in bytes (default 4GB) -| ```-maxexpiry 86400``` | maximum expiration time in seconds (default is 0, which is no expiry) -| ```-allowhotlink``` | Allow file hotlinking -| ```-contentsecuritypolicy "..."``` | Content-Security-Policy header for pages (default is "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';") -| ```-filecontentsecuritypolicy "..."``` | Content-Security-Policy header for files (default is "default-src 'none'; img-src 'self'; object-src 'self'; media-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';") -| ```-refererpolicy "..."``` | Referrer-Policy header for pages (default is "same-origin") -| ```-filereferrerpolicy "..."``` | Referrer-Policy header for files (default is "same-origin") -| ```-xframeoptions "..." ``` | X-Frame-Options header (default is "SAMEORIGIN") -| ```-remoteuploads``` | (optionally) enable remote uploads (/upload?url=https://...) -| ```-nologs``` | (optionally) disable request logs in stdout -| ```-force-random-filename``` | (optionally) force the use of random filenames -| ```-custompagespath "custom_pages"``` | (optionally) specify path to directory containing markdown pages (must end in .md) that will be added to the site navigation (this can be useful for providing contact/support information and so on). For example, custom_pages/My_Page.md will become My Page in the site navigation +| ```bind = 127.0.0.1:8080``` | what to bind to (default is 127.0.0.1:8080) +| ```sitename = myLinx``` | the site name displayed on top (default is inferred from Host header) +| ```siteurl = https://mylinx.example.org/``` | the site url (default is inferred from execution context) +| ```selifpath = selif``` | path relative to site base url (the "selif" in mylinx.example.org/selif/image.jpg) where files are accessed directly (default: selif) +| ```maxsize = 4294967296``` | maximum upload file size in bytes (default 4GB) +| ```maxexpiry = 86400``` | maximum expiration time in seconds (default is 0, which is no expiry) +| ```allowhotlink = true``` | Allow file hotlinking +| ```contentsecuritypolicy = "..."``` | Content-Security-Policy header for pages (default is "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';") +| ```filecontentsecuritypolicy = "..."``` | Content-Security-Policy header for files (default is "default-src 'none'; img-src 'self'; object-src 'self'; media-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'self';") +| ```refererpolicy = "..."``` | Referrer-Policy header for pages (default is "same-origin") +| ```filereferrerpolicy = "..."``` | Referrer-Policy header for files (default is "same-origin") +| ```xframeoptions = "..." ``` | X-Frame-Options header (default is "SAMEORIGIN") +| ```remoteuploads = true``` | (optionally) enable remote uploads (/upload?url=https://...) +| ```nologs = true``` | (optionally) disable request logs in stdout +| ```force-random-filename = true``` | (optionally) force the use of random filenames +| ```custompagespath = custom_pages/``` | (optionally) specify path to directory containing markdown pages (must end in .md) that will be added to the site navigation (this can be useful for providing contact/support information and so on). For example, custom_pages/My_Page.md will become My Page in the site navigation #### Cleaning up expired files @@ -100,16 +107,16 @@ will persist on disk until someone attempts to access them. You can set the foll |Option|Description |------|----------- -| ```-cleanup-every-minutes 5``` | How often to clean up expired files in minutes (default is 0, which means files will be cleaned up as they are accessed) +| ```cleanup-every-minutes = 5``` | How often to clean up expired files in minutes (default is 0, which means files will be cleaned up as they are accessed) #### Require API Keys for uploads |Option|Description |------|----------- -| ```-authfile path/to/authfile``` | (optionally) require authorization for upload/delete by providing a newline-separated file of scrypted auth keys -| ```-remoteauthfile path/to/remoteauthfile``` | (optionally) require authorization for remote uploads by providing a newline-separated file of scrypted auth keys -| ```-basicauth``` | (optionally) allow basic authorization to upload or paste files from browser when `-authfile` is enabled. When uploading, you will be prompted to enter a user and password - leave the user blank and use your auth key as the password +| ```authfile = path/to/authfile``` | (optionally) require authorization for upload/delete by providing a newline-separated file of scrypted auth keys +| ```remoteauthfile = path/to/remoteauthfile``` | (optionally) require authorization for remote uploads by providing a newline-separated file of scrypted auth keys +| ```basicauth = true``` | (optionally) allow basic authorization to upload or paste files from browser when `-authfile` is enabled. When uploading, you will be prompted to enter a user and password - leave the user blank and use your auth key as the password A helper utility ```linx-genkey``` is provided which hashes keys to the format required in the auth files. @@ -118,25 +125,25 @@ The following storage backends are available: |Name|Notes|Options |----|-----|------- -|LocalFS|Enabled by default, this backend uses the filesystem|```-filespath files/``` -- Path to store uploads (default is files/)
```-metapath meta/``` -- Path to store information about uploads (default is meta/)| -|S3|Use with any S3-compatible provider.
This implementation will stream files through the linx instance (every download will request and stream the file from the S3 bucket).

For high-traffic environments, one might consider using an external caching layer such as described [in this article](https://blog.sentry.io/2017/03/01/dodging-s3-downtime-with-nginx-and-haproxy.html).|```-s3-endpoint https://...``` -- S3 endpoint
```-s3-region us-east-1``` -- S3 region
```-s3-bucket mybucket``` -- S3 bucket to use for files and metadata
```-s3-force-path-style``` (optional) -- force path-style addresing (e.g. https://s3.amazonaws.com/linx/example.txt)

Environment variables to provide:
```AWS_ACCESS_KEY_ID``` -- the S3 access key
```AWS_SECRET_ACCESS_KEY ``` -- the S3 secret key
```AWS_SESSION_TOKEN``` (optional) -- the S3 session token| +|LocalFS|Enabled by default, this backend uses the filesystem|```filespath = files/``` -- Path to store uploads (default is files/)
```metapath = meta/``` -- Path to store information about uploads (default is meta/)| +|S3|Use with any S3-compatible provider.
This implementation will stream files through the linx instance (every download will request and stream the file from the S3 bucket).

For high-traffic environments, one might consider using an external caching layer such as described [in this article](https://blog.sentry.io/2017/03/01/dodging-s3-downtime-with-nginx-and-haproxy.html).|```s3-endpoint = https://...``` -- S3 endpoint
```s3-region = us-east-1``` -- S3 region
```s3-bucket = mybucket``` -- S3 bucket to use for files and metadata
```s3-force-path-style = true``` (optional) -- force path-style addresing (e.g. https://s3.amazonaws.com/linx/example.txt)

Environment variables to provide:
```AWS_ACCESS_KEY_ID``` -- the S3 access key
```AWS_SECRET_ACCESS_KEY ``` -- the S3 secret key
```AWS_SESSION_TOKEN``` (optional) -- the S3 session token| #### SSL with built-in server |Option|Description |------|----------- -| ```-certfile path/to/your.crt``` | Path to the ssl certificate (required if you want to use the https server) -| ```-keyfile path/to/your.key``` | Path to the ssl key (required if you want to use the https server) +| ```certfile = path/to/your.crt``` | Path to the ssl certificate (required if you want to use the https server) +| ```keyfile = path/to/your.key``` | Path to the ssl key (required if you want to use the https server) #### Use with http proxy |Option|Description |------|----------- -| ```-realip``` | let linx-server know you (nginx, etc) are providing the X-Real-IP and/or X-Forwarded-For headers. +| ```realip = true``` | let linx-server know you (nginx, etc) are providing the X-Real-IP and/or X-Forwarded-For headers. #### Use with fastcgi |Option|Description |------|----------- -| ```-fastcgi``` | serve through fastcgi +| ```fastcgi = true``` | serve through fastcgi Deployment ---------- @@ -161,10 +168,10 @@ server { } } ``` -And run linx-server with the ```-fastcgi``` option. +And run linx-server with the ```fastcgi = true``` option. #### 2. Using the built-in https server -Run linx-server with the ```-certfile path/to/cert.file``` and ```-keyfile path/to/key.file``` options. +Run linx-server with the ```certfile = path/to/cert.file``` and ```keyfile = path/to/key.file``` options. #### 3. Using the built-in http server Run linx-server normally. diff --git a/linx-server.conf.example b/linx-server.conf.example new file mode 100644 index 0000000..eb2e1f8 --- /dev/null +++ b/linx-server.conf.example @@ -0,0 +1,12 @@ + +bind = 127.0.0.1:8080 +sitename = myLinx +siteurl = https://mylinx.example.org/ +selifpath = s +maxsize = 4294967296 +maxexpiry = 86400 +allowhotlink = true +remoteuploads = true +nologs = true +force-random-filename = false +cleanup-every-minutes = 5 \ No newline at end of file