Skip to content

Latest commit

聽

History

History
134 lines (107 loc) 路 8.6 KB

README.md

File metadata and controls

134 lines (107 loc) 路 8.6 KB
Raw

Andesite

loc license discord paypal circleci release goreportcard codefactor downloads issuehunt docker_pulls docker_stars

Share folders in an Open Directory without making your entire server public. Manages users with OAuth2.

Getting Started

These instructions will help you get the project up and running. To obtain the binary you will use to run the app, follow the Development or Deployment sections for futher direction. Below, are general directions for all builds.

Options

Use these to configure your Andesite instance. All are optional. "Name" refers to the name of the CLI flag that may be used. "Config Name" refers to the key name inside of your config.json. More on that later.

Name Config Name Type Default Description
--root "root" string none. Path of root directory for /files/.
--public "public" string none. Path of root directory for /public/.
--port "port" int 8000 Port for web server to bind to.
--base "base" string / HTTP path of app root.
--config n/a. string ~/.config/andesite/config.json The path to the config.json file used for app configuration.
--enable-search "search_on" string[] none. Names of roots to scan and add to the file database.
--disable-search "search_off" string[] none. Names of roots to remove from the file database.
"roots_public" string[][] none. Enabled roots that don't lie on /public/ by adding entries [url_path,fs_path].
"roots_private" string[][] none. Enabled roots that don't lie on /filess/ by adding entries [url_path,fs_path].
--verbose "verbose" boolean false Set to true to enable verbose logging.
--fsdb-verbose "verbose_fsdb" boolean false Set to true to enable verbose fsdb logging.
--disable-hash string[] none. Any of md5, sha1, sha256, sha512, sha3, blake2b.
--hash-concurrency int cpu count Number of hashes to run concurrently.
--custom-root-public string[] none Similar to "roots_public", passed in the form name=path.
--custom-root-private string[] none Similar to "roots_private", passed in the form name=path.
--disable-global-search bool false When true, /search requires being an admin to use.

Note: for --enable-search and --disable-search, sending values to these flags will trigger a background scan of the root directory you point it at (whether that be public, files, etc). As such, unless content is changed or updated, it is not necessary to pass these flags across multiple runs of the app.

Creating Credentials

In order to create a "closed directory" with Andesite, you will need to create an app on your Identity Provider(s) of choice. See the nektro/go.oauth2 docs for more detailed info on this process on where to go and what data you'll need.

Here you can also fill out a picture and description that will be displayed during the authorization of users on your chosen Identity Provider. When prompted for the "Redirect URI" during the app setup process, the URL to use will be http://andesite/callback, replacing andesite with any origins you wish Andesite to be usable from, such as example.com or localhost:800.

Once you have finished the app creation process you should now have a Client ID and Client Secret. These are passed into Andesite through flags as well.

The Identity Provider IDs used below can be found in the table in the nektro/go.oauth2 documentation under the "Short Code" column.

Name Type Default Description
--oauth2-client string[] none. `idp_id

Deployment

Pre-compiled binaries can be obtained from https://github.com/nektro/andesite/releases/latest.

Or from Docker docker run nektro/andesite

Development

Prerequisites

Installing

Run

$ go get -v -u github.com/nektro/andesite

and then make your way to $GOPATH/src/github.com/nektro/andesite/.

Once there, run:

$ go build
$ ./andesite

Extras

Discord Guild/Role Access Grant

Due to a limitation in the Discord API, in order to determine if a user has a role on a specific server, you must use a bot. To get started, go to https://discordapp.com/developers/applications/ and add a Bot user to your app and copy down the Bot Token. Now, to be able to give file/folder access to entire roles, we are going to be using more flags:

Name Config Name Type Default Description
--discord-guild-id "clients[for.discord].extra_1" string none. Guild Snowflake.
--discord-bot-token "clients[for.discord].extra_2" string none. Bot Token.

Enabling these values will add a section to http://andesite/admin that you can input the role snowflakes and the path you are granting.

Themes

Andesite supports making custom themes for the splash page and the various HTML templates throughout the program. Those are:

  • index.html - Default Source
    • The main page shown to all users at the root of the server.
  • response.hbs - Default Source
    • A generic page used to show errors and message to the user.
  • listing.hbs - Default Source
    • The main directory listing page.
  • admin.hbs - Default Source
    • The admin dashboard that allows editing the access of users.
  • style.css - Default Source
    • Empty CSS file you can use to easily make style-only themes.
  • users.hbs - Default Source
    • The admin dashboard that allows viewing of the list of users.
  • admin_roots.hbs - Default Source
    • The admin dashboard that allows viewing of all the data paths.

All or none of the files may be replaced when using a theme. To enable use of a theme, suppose the value passed to --theme was example. Doing this will tell Andesite to serve files from .andesite/themes/example/.

Built With

Contributing

issues

We listen to issues all the time right here on GitHub. Labels are extensively to show the progress through the fixing process. Question issues are okay but make sure to close the issue when it has been answered! Off-topic and '+1' comments will be deleted. Please use post/comment reactions for this purpose.

Contact

License

Apache 2.0