README: Clarify docker usage and example

This commit is contained in:
Andrei Marcu 2020-05-14 00:51:19 -07:00
parent 151515f516
commit e2a65a5b62
3 changed files with 57 additions and 37 deletions

1
.gitignore vendored
View File

@ -31,6 +31,7 @@ _testmain.go
linx-server
linx-cleanup/linx-cleanup
linx-genkey/linx-genkey
linx-server.conf
files/
meta/
binaries/

View File

@ -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"
@ -58,39 +64,40 @@ Ideally, you would use a reverse proxy such as nginx or caddy to handle TLS cert
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
maxexpiry = 86400
# ... etc
```
...and then invoke ```linx-server -config path/to/config.ini```
...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/)<br />```-metapath meta/``` -- Path to store information about uploads (default is meta/)|
|S3|Use with any S3-compatible provider.<br> This implementation will stream files through the linx instance (every download will request and stream the file from the S3 bucket).<br><br>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<br>```-s3-region us-east-1``` -- S3 region<br>```-s3-bucket mybucket``` -- S3 bucket to use for files and metadata<br>```-s3-force-path-style``` (optional) -- force path-style addresing (e.g. https://<span></span>s3.amazonaws.com/linx/example.txt)<br><br>Environment variables to provide:<br>```AWS_ACCESS_KEY_ID``` -- the S3 access key<br>```AWS_SECRET_ACCESS_KEY ``` -- the S3 secret key<br>```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/)<br />```metapath = meta/``` -- Path to store information about uploads (default is meta/)|
|S3|Use with any S3-compatible provider.<br> This implementation will stream files through the linx instance (every download will request and stream the file from the S3 bucket).<br><br>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<br>```s3-region = us-east-1``` -- S3 region<br>```s3-bucket = mybucket``` -- S3 bucket to use for files and metadata<br>```s3-force-path-style = true``` (optional) -- force path-style addresing (e.g. https://<span></span>s3.amazonaws.com/linx/example.txt)<br><br>Environment variables to provide:<br>```AWS_ACCESS_KEY_ID``` -- the S3 access key<br>```AWS_SECRET_ACCESS_KEY ``` -- the S3 secret key<br>```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.

12
linx-server.conf.example Normal file
View File

@ -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