Skip to content

Latest commit

 

History

History
158 lines (147 loc) · 5.48 KB

web.org

File metadata and controls

158 lines (147 loc) · 5.48 KB
Raw

Web Documentation

Dotfilehub

Dotfilehub is a web interface for Dotfile. It does not use JavaScript and should be usable with basic browsers.

The index page is a form that does a global search. It finds files that have aliases or paths that match any part of the query. Results can be ordered by clicking the links on the table header. This is also available as a RSS feed.

Files

View

All files are globally viewable at the path /{username}/{alias}. There are no private files.

Files only render in HTML if the client sends an accept header that contains html. This allows users to download files easily if they are in an environment without the Dotfile CLI. For example:

curl https://dotfilehub.com/knoebber/bashrc > ~/.bashrc

Create

Creating a file online is the same as pushing a file with the CLI.

To create a file, login and navigate to your username. Click the “new file” link at the top. Enter an alias, a path, and the files content.

The alias must contain only letters, numbers, and underscores. When alias is omitted it will be generated from the path.

The path is the location that the CLI will install the file to. Paths must start in either / or ~/, E.G. ~/.bashrc, /etc/aliases. It cannot have a trailing slash.

Carriage return characters - “\r” - are stripped from the file content before being saved.

Edit

Editing a file is the same as committing changes with the CLI. This will show the diff before confirming the new change. Commits can be rolled back by selecting a different commit and hitting “revert”.

Like create, all carriage return characters are stripped from the edited file.

Settings

File settings provides the following options:

  • Update a file’s alias or path
  • Remove all commits except the current
  • Delete the file

Note that changing the alias or path can cause CLI operations that use the API to throw errors.

User Settings

Setup CLI

Select “Setup CLI” and enter the commands into a shell. The token can be rotated at anytime - this ends all CLI write access until it’s reconfigured with the new token.

Set Timezone

This will convert timestamps from the database to a timezone. The default is UTC. The form expects a string like the TZ database name column found here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Depending on the server’s host the available zones may be different. Consult https://golang.org/pkg/time/#LoadLocation for more information.

Account Recovery

To enable account recovery save an email to your account. Emails are not used for anything else and are not visible by other users.

Delete Account

This will delete all user data including files, commits, and session data.

API

See https://github.com/knoebber/dotfile/tree/master/dotfileclient/dotfileclient.go for an example of building a client for the Dotfile API.

List Files

GET /api/v1/user/{username}
GET /api/v1/user/{username}?path=true

Returns a list of aliases for username. Include paths with the ?path parameter.

Get File Data

GET /api/v1/user/{username}/{alias}

Returns a file’s data in JSON format.

Get Raw Content

GET /api/v1/user/{username}/{alias}/raw

Uncompresses the current revision.

Get Revision

GET /api/v1/user/{username}/{alias}/{hash}

Returns a file’s compressed revision at hash.

Push File

POST /api/v1/user/{username}/{alias}

Post a file to the server. This can either be a new or existing file. The request body is a multipart file upload. The first part is a JSON encoding of the file data. Every hash that is part of the file’s data should have a corresponding file part in the request. The file parts are zlib compressed revisions that are named as the uncompressed contents hash.

The request must have basic auth headers with the dotfilehub username and CLI token as the password.

Self host

Clone the repository and build the binary. All assets are embedded into the dotfilehub binary so it can be moved anywhere after. 
git clone https://github.com/knoebber/dotfile
cd dotfile
make dotfilehub
./bin/dotfilehub

The server is configured through the following optional flags:

-addr

The address to listen on. Defaults to localhost:3000.

-db

The location of the sqlite database. Creates a new database when it does not yet exist. Defaults to ~/.dotfilehub.db.

-host

The name of the host. Used for displaying the host name in the CLI setup page and the password reset email. If this is not set the server will use the host header which is often incorrect. This shouldn’t contain http:// or https://.

-secure

Boolean flag, defaults false. Set this to true when the host is using HTTPS.

-proxyheaders

Boolean flag, defaults false. When true, the server will log request IPs by inspecting reverse proxy headers.

-smtp-config-path

Sets up a SMTP client for account recovery. The value should be a path to a JSON file. The file must contain the following keys:

{
    "host": "",
    "port": 0,
    "username": "",
    "password": "",
    "sender": ""
}

The client will use PLAIN authentication.

Example

dotfilehub.com is currently hosted with fly.io, for an example Dockerfile and fly.toml, see the top level of https://github.com/knoebber/dotfile