docshelf

package module
v0.0.0-...-4f898de Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2020 License: MIT Imports: 2 Imported by: 0

README

DocShelf

build coverage documentation

A lightweight, team documentation solution that won't make you pull your hair out.

!WIP!

This project is still a pre-alpha work in progress and isn't suitable for any real use cases yet. Come back soon though! 😄

Quickstart

The fastest way to get up and running with docshelf is to spin everything up with docker compose.

$ docker compose up

Navigating to http://localhost:9001/ should pop up a login window.

Running with docker-compose runs the UI as a dev server, so bundles should be updated as you make changes (although you will have to manually refresh your browser). The API also has rudimentary "hot reloading". Any time you modify a go file, a new build will be generated and the running binary will be replaced.

Local Development

API

To get the docshelf API running natively on your local machine, you just need to have the go compiler installed.

$ go run cmd/server/main.go

When docshelf starts up, it will spin up a local bolt database, a bleve search index, and all documents will be stored locally in a documents/ folder.

Experimental UI

There's curently a bare bones UI, written in svelte, that serves as a nicer way of testing docshelf features than running dozens of postman requests. You can run the dev server with npm.

$ cd ui/
$ npm install
$ npm run dev
Caddy reverse proxy

In order to serve both the UI and the API under the same domain (localhost:9001 is the default), you can proxy through caddy. Download the binary release for your system from the caddy download page.

From the root of the project:

$ caddy start

Once caddy, the UI dev server, and API are all running, you should be able to navigate to https://localhost:9001/ to load docshelf.

Backends

AWS

If you want to test docshelf with the AWS backends, all you have to do is set some environment variables. This assumes that your AWS credentials are already present in your environment.

Dynamo Backend
$ DS_BACKEND=dynamo go run cmd/server/main.go

Docshelf will automatically provision the necessary dynamo tables if they don't exist, so give it a minute or two on the first startup.

S3 File Store
$ DS_FILE_BACKEND=s3 DS_S3_BUCKET=docshelf-test go run cmd/server/main.go

Configuration

Currently, docshelf can only be configured through environment variables. This table shows all of the current options that can be set.

Var Possible Values Description
DS_BACKEND bolt, dynamo Backend for users, doc metadata, etc.
DS_FILE_BACKEND disk, s3 How to store document content
DS_TEXT_INDEX bleve, elastic* What text index to use for search
DS_S3_BUCKET string The bucket to use with the s3 file backend
DS_FILE_PREFIX string The path/prefix to apply to all saved documents
DS_HOST string The host for the API to listen on
DS_PORT 0-65535 The port for the API to listen on
DS_GOOGLE_CLIENT_ID string The google client ID to use during oauth
DS_GOOGLE_CLIENT_SECRET string The google client secret to use during oauth
DS_GITHUB_CLIENT_ID string The github client ID to use during oauth
DS_GITHUB_CLIENT_SECRET string The github client secret to use during oauth

*elastic is not currenlty supported, but will be in the near future

More configuration options will become available as dochself becomes more full-featured.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckNotFound 

func CheckNotFound(err error) bool

CheckNotFound is a helper function for determining if an error type is actually an ErrNotFound.

func CheckRemoved 

func CheckRemoved(err error) bool

CheckRemoved is a helper function for determining if an error type is actually an ErrRemoved.

func NewErrNotFound 

func NewErrNotFound(msg string) error

NewErrNotFound returns a new ErrNotFound as a normal error containing the given message.

func NewErrRemoved 

func NewErrRemoved(msg string) error

NewErrRemoved returns a new ErrRemoved as a normal error containing the given message.

Types

type Authenticator 

type Authenticator interface {
	Authenticate(ctx context.Context, email, token string) (User, error)
}

An Authenticator knows how to authenticate user credentials.

type Backend 

type Backend interface {
	DocStore
	UserStore
	GroupStore
}

A Backend is an aggregation of almost all docshelf store interfaces.

type Doc 

type Doc struct {
	ID        string    `json:"id"`
	Path      string    `json:"path"`
	Title     string    `json:"title"`
	IsDir     bool      `json:"isDir"`
	Content   string    `json:"content,omitempty"`
	Policy    *Policy   `json:"policy"`
	Tags      []string  `json:"tags"`
	CreatedBy string    `json:"createdBy"`
	UpdatedBy string    `json:"updatedBy"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

A Doc is a full docshelf document. This includes metadata as well as content.

func (Doc) ContentString 

func (d Doc) ContentString() string

ContentString returns a Doc's content as a string.

type DocStore 

type DocStore interface {
	GetDoc(ctx context.Context, path string) (Doc, error)
	ListDocs(ctx context.Context, query string, tags ...string) ([]Doc, error)
	PutDoc(ctx context.Context, doc Doc) (string, error)
	TagDoc(ctx context.Context, path string, tags ...string) error
	RemoveDoc(ctx context.Context, path string) error
}

A DocStore knows how to store and retrieve docshelf documents.

type ErrNotFound 

type ErrNotFound struct {
	// contains filtered or unexported fields
}

ErrNotFound is a special error type for signaling that a requested entity doesn't exist.

func (ErrNotFound) Error 

func (e ErrNotFound) Error() string

Error implements the Error interface for ErrNotFound. Default messaging is used if not supplied.

type ErrRemoved 

type ErrRemoved struct {
	// contains filtered or unexported fields
}

ErrRemoved is a special error type for signaling that a requested entity has been removed.

func (ErrRemoved) Error 

func (e ErrRemoved) Error() string

Error implements the Error interface for ErrRemoved. Default messaging is used if not supplied.

type FileStore 

type FileStore interface {
	ReadFile(path string) ([]byte, error)
	WriteFile(path string, data []byte) error
	RemoveFile(path string) error
	ListDir(path string) ([]string, error)
}

A FileStore knows how to store and retrieve docshelf document contents.

type Group 

type Group struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Users     []string  `json:"users"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

A Group is collection of Users for the purposes of granting access.

type GroupStore 

type GroupStore interface {
	GetGroup(ctx context.Context, id string) (Group, error)
	PutGroup(ctx context.Context, group Group) (string, error)
	RemoveGroup(ctx context.Context, id string) error
}

A GroupStore knows how to store and retrieve docshelf Groups.

type Policy 

type Policy struct {
	ID        string    `json:"id"`
	Users     []string  `json:"users"`
	Groups    []string  `json:"groups"`
	ReadOnly  bool      `json:"readOnly"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

An Policy defines the users and groups that have access to a particular file path.

type PolicyStore 

type PolicyStore interface {
	GetPolicy(ctx context.Context, id string) (Policy, error)
	PutPolicy(ctx context.Context, policy Policy) (string, error)
	RemovePolicy(ctx context.Context, id string) (string, error)
}

A PolicyStore knows how to store and retrieve docshelf Policies.

type TextIndex 

type TextIndex interface {
	Index(ctx context.Context, doc Doc) error
	Search(ctx context.Context, term string) ([]string, error)
}

An TextIndex knows how to index and search docshelf documents.

type User 

type User struct {
	ID        string     `json:"id"`
	Email     string     `json:"email"`
	Name      string     `json:"name"`
	Token     string     `json:"token"`
	Groups    []string   `json:"groups"`
	Pinned    []string   `json:"pinned"`
	CreatedAt time.Time  `json:"createdAt"`
	UpdatedAt time.Time  `json:"updatedAt"`
	DeletedAt *time.Time `json:"deletedAt"`
}

A User is the identity of anyone using docshelf.

type UserStore 

type UserStore interface {
	GetUser(ctx context.Context, id string) (User, error)
	// GetEmail(ctx context.Context, email string) (User, error)
	ListUsers(ctx context.Context) ([]User, error)
	PutUser(ctx context.Context, user User) (string, error)
	RemoveUser(ctx context.Context, id string) error
}

A UserStore knows how to store and retrieve docshelf users.

Source Files

View all Source files

Directories

Path Synopsis
cmd
server

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.