fmartingr
/
shiori
mirror of https://github.com/fmartingr/shiori.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
shiori/docs/faq.md

8.7 KiB
Raw Blame History

Contents

General

Common issues

Advanced

General

What is this project ?

Shiori is a bookmarks manager that built with Go. I've got the idea to make this after reading a comment on HN back in April 2017 :

... for me the dream bookmark manager would be something really simple 
with two commands like:

$ bookmark add http://...

That will:

a. Download a static copy of the webpage in a single HTML file, with a
   PDF exported copy, that also take care of removing ads and 
   unrelated content from the stored content.
b. Run something like http://smmry.com/ to create a summary of the page
   in few sentences and store it.
c. Use NLP techniques to extract the principle keywords and use them 
   as tags

And another command like:

$ bookmark search "..."

That will:

d. Not use regexp or complicated search pattern, but instead;
e. Search titles, tags, page content smartly and interactively, and;
f. Sort/filter results smartly by relevance, number of matches, 
   frequency, or anything else useful
g. Storing everything in a git repository or simple file structure 
   for easy synchronization, bonus point for browsers integrations.

I do like using bookmarks and those idea sounds useful to me. More importantly, it seems possible enough to do. Not too hard that it's impossible for me, but not too easy that it doesn't teach me anything. Looking back now, the only thing that I (kind of) managed to do is a, b, d and e. But it's enough for me, so it's fine I guess 😆.

How does it compare to other bookmarks manager ?

To be honest I don't know. The only bookmarks manager that I've used is Pocket and the one that bundled in web browser. I do like Pocket though. However, since bookmarks is kind of sensitive data, I prefer it stays offline or in my own server.

What are the system requirements ?

It runs in the lowest tier of Digital Ocean VPS, so I guess it should be able to run anywhere.

What is the status for this app ?

It's stable enough to use and the database shouldn't be changed anymore. However, my bookmarks at most is only several hundred entries, therefore I haven't test whether it able to process or imports huge amount of bookmarks. If you would, please do try it.

Is this app actively maintained ?

Yes, however the development pace might be really slow, especially when my day job is in busy season.

How to make a contribution ?

Just like other open source projects, you can make a contribution by submitting issues or pull requests.

How to make a donation ?

If you like this project, you can donate to me either via PayPal or Ko-Fi.

Common Issues

Where is MacOS prebuilt binary ?

Since shiori is using SQLite, it needs to be compiled using cgo. Therefore, to cross compile it from Linux, we need a cross compiler for darwin. This is hard because we need to download XCode and Apple's GCC compiler. There are multiple guides on how to do this, however I haven't got the time to do it. For more detail, you can check this issue which trying to do it.

What is the default account to login at the first time ?

The default account is shiori with password gopher. It is removed once another 'owner' account is created.

Why my old accounts can't do anything after upgrading Shiori to v1.5.0 ?

This issue happened because in Shiori v1.0.0 there are no account level, which means everyone is treated as owner. However, in Shiori v1.5.0 there are two account levels i.e. owner and visitor. The level difference is stored in database as boolean value in column owner with default value false (which means by default all account is visitor, unless specified otherwise).

Because in v1.5.0 by default all account is visitor, when updating from v1.0 to v1.5 all of the old accounts by default will be marked as visitor. Fortunately, when there are no owner registered in database, we can login as owner using default account.

So, as workaround for this issue, you should :

  • Login as default account.
  • Go to options page.
  • Remove your old accounts.
  • Recreate them, but now as owner.

For more details see #148.

Advanced

How to run shiori on start up ?

There are several methods to run shiori on start up, however the most recommended is running it as a service.

  1. Create a service unit for systemd at /etc/systemd/system/shiori.service.

  • Shiori is run via docker :

    [Unit]
Description=Shiori container
After=docker.service

[Service]
Restart=always
ExecStartPre=-/usr/bin/docker rm shiori-1
ExecStart=/usr/bin/docker run \
  --rm \
  --name shiori-1 \
  -p 8080:8080 \
  -v /srv/machines/shiori:/srv/shiori \
  radhifadlillah/shiori
ExecStop=/usr/bin/docker stop -t 2 shiori-1

[Install]
WantedBy=multi-user.target

  • Shiori without docker. Set absolute path to shiori binary. --portable sets the data directory to be alongside the executable.

    [Unit]
Description=Shiori service

[Service]
ExecStart=/home/user/go/bin/shiori serve --portable
Restart=always

[Install]
WantedBy=multi-user.target

  • Shiori without docker and without --portable but secure.

[Unit]
Description=shiori service
Requires=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/shiori serve
Restart=always
User=shiori
Group=shiori

Environment="SHIORI_DIR=/var/lib/shiori"
DynamicUser=true
PrivateUsers=true
ProtectHome=true
ProtectKernelLogs=true
RestrictAddressFamilies=AF_INET AF_INET6
StateDirectory=shiori
SystemCallErrorNumber=EPERM
SystemCallFilter=@system-service
SystemCallFilter=~@chown
SystemCallFilter=~@keyring
SystemCallFilter=~@memlock
SystemCallFilter=~@setuid
DeviceAllow=

CapabilityBoundingSet=
LockPersonality=true
MemoryDenyWriteExecute=true
NoNewPrivileges=true
PrivateDevices=true
PrivateTmp=true
ProtectControlGroups=true
ProtectKernelTunables=true
ProtectSystem=full
ProtectClock=true
ProtectKernelModules=true
ProtectProc=noaccess
ProtectHostname=true
ProcSubset=pid
RestrictNamespaces=true
RestrictRealtime=true
RestrictSUIDSGID=true
SystemCallArchitectures=native
SystemCallFilter=~@clock
SystemCallFilter=~@debug
SystemCallFilter=~@module
SystemCallFilter=~@mount
SystemCallFilter=~@raw-io
SystemCallFilter=~@reboot
SystemCallFilter=~@privileged
SystemCallFilter=~@resources
SystemCallFilter=~@cpu-emulation
SystemCallFilter=~@obsolete
UMask=0077

[Install]
WantedBy=multi-user.target

  1. Set up data directory if Shiori with docker

    This assumes, that the Shiori container has a runtime directory to store their database, which is at /srv/machines/shiori. If you want to modify that, make sure, to fix your shiori.service as well.

    install -d /srv/machines/shiori

  2. Enable and start the service

    systemctl enable --now shiori

How to cross compile from Linux to Windows ?

First we need to install mingw-w64 for cross compiling. Assuming you are using Ubuntu the command will look like this :

$ sudo apt-get install gcc-mingw-w64

Now we can build for Windows 64-bit and 32-bit. To do so, cd to the shiori directory then run following commands :

# For Windows 64-bit
GOOS=windows GOARCH=amd64 CC=x86_64-w64-mingw32-gcc CGO_ENABLED=1 go build -o shiori-windows-amd64.exe

# For Windows 32-bit
GOOS=windows GOARCH=386 CC=i686-w64-mingw32-gcc CGO_ENABLED=1 go build -o shiori-windows-386.exe