An unofficial, mostly Bitwarden-compatible API server written in Ruby (Sinatra and ActiveRecord)
Start storing production sqlite3 db in db/production/
Also move AR migration docs to separate file since they won't be
needed for long.
+74
-56
+45
AR-MIGRATE.md
+45
AR-MIGRATE.md
···
1
+
## bitwarden-ruby
2
+
3
+
### Migrating to ActiveRecord
4
+
5
+
If you've used this application before it switched to using ActiveRecord, you
6
+
need to do the following steps to migrate the data and generate the new table
7
+
structures.
8
+
9
+
Even though the migration script will create a backup of your database, it is
10
+
probably best to create a backup yourself.
11
+
You can also copy the `db/production.sqlite3` to your local machine and do the
12
+
migration there.
13
+
14
+
After a successful migration you'd have to copy the updated database file back
15
+
to the production machine.
16
+
17
+
First make sure you have the latest code:
18
+
19
+
git pull
20
+
21
+
Afterwards you need to run bundle to add some required libraries for the migration
22
+
23
+
bundle --with migrate
24
+
25
+
Now you are ready to do the migration:
26
+
27
+
bundle exec ruby tools/migrate_to_ar.rb -e production
28
+
29
+
The -e switch allows you to select the correct database environment from
30
+
`db/config.yml`.
31
+
The migration script will:
32
+
33
+
- dump the contents of the database to a YAML file
34
+
- rename the original database file to `production.sqlite3.#{Time.now.to_i}`
35
+
- create the database using ActiveRecord migrations
36
+
- load the contents from the dump file
37
+
- remove the dump file
38
+
39
+
Now your data is completely migrated and the library will now use ActiveRecord
40
+
to handle anything database related.
41
+
42
+
Note: The ActiveRecord migration also defaults to putting the production
43
+
database files in `db/production/` instead of just `db/`, which allows for
44
+
a separate user to be able to write to the SQLite file without writing to
45
+
`db/config.yml` and `db/migrate/` files.
+27
-54
README.md
+27
-54
README.md
···
14
14
This means you can easily run the server locally and have your data never
15
15
leave your device, or run it on your own web server via Rack and some front-end
16
16
HTTP server with TLS to support syncing across multiple devices.
17
-
Backing up your data is as easy as copying the `db/production.sqlite3` file
18
-
somewhere.
17
+
Backing up your data is as easy as copying the `db/production/production.sqlite3`
18
+
file somewhere.
19
19
20
20
All user data in the SQLite database is stored in an encrypted format the
21
21
[same way](https://help.bitwarden.com/crypto.html)
···
37
37
38
38
Run `bundle install` at least once.
39
39
40
-
In order to create the database and the required tables run:
40
+
In order to create the initial environment, it is recommended to create a new,
41
+
unprivileged user on your system dedicated to running bitwarden-ruby such as
42
+
with `useradd`.
43
+
This documentation will assume a user has been created named `_bitwarden`.
44
+
45
+
In order to create the initial database and the required tables run:
46
+
47
+
mkdir db/production
48
+
sudo chown _bitwarden db/production
49
+
sudo -u _bitwarden env RACK_ENV=production bundle exec rake db:migrate
41
50
42
-
env RACK_ENV=production bundle exec rake db:migrate
51
+
If you've previously used bitwarden-ruby before July 30, 2018, when it did not
52
+
use ActiveRecord, you should instead
53
+
[migrate](AR-MIGRATE.md)
54
+
your existing database.
43
55
44
-
To run via Rack on port 4567:
56
+
To run via Rack on port 4567, as user `_bitwarden`:
45
57
46
-
env RACK_ENV=production bundle exec rackup -p 4567 config.ru
58
+
sudo -u _bitwarden env RACK_ENV=production bundle exec rackup -p 4567 config.ru
47
59
48
60
You'll probably want to run it once with signups enabled, to allow yourself
49
61
to create an account:
50
62
51
-
env RACK_ENV=production ALLOW_SIGNUPS=1 bundle exec rackup -p 4567 config.ru
63
+
sudo -u _bitwarden env RACK_ENV=production ALLOW_SIGNUPS=1 bundle exec rackup -p 4567 config.ru
52
64
53
65
Once the server is running, the Bitwarden apps (such as the Firefox extension)
54
66
can be configured to use your own Bitwarden server before login.
···
64
76
requires interacting with the plaintext password, which the web API will never
65
77
do).
66
78
67
-
```
68
-
env RACK_ENV=production bundle exec ruby tools/change_master_password.rb -u you@example.com
69
-
```
70
-
71
-
### Migrating to ActiveRecord
72
-
73
-
If you've used this library before it switched to using ActiveRecord, you need to do the following steps to migrate the data and generate the new table structures. Even though the migration script will create a backup of your database, it is probably best to create a backup yourself. You can also copy the ```db/production.sqlite3``` to your local machine and do the migration there. After a successful migration you'd have to copy the updated database file back to the production machine.
74
-
75
-
First make sure you have the latest code:
76
-
77
-
git pull
78
-
79
-
Afterwards you need to run bundle to add some required libraries for the migration
80
-
81
-
bundle --with migrate
82
-
83
-
Now you are ready to do the migration
84
-
85
-
ruby tools/migrate_to_ar.rb -e production
86
-
87
-
The -e switch allows you to select the correct database environment from db/config.yml. The migration script will:#
88
-
89
-
* dump the contents of the database to a YAML file
90
-
* rename the original database file to ```production.sqlite3.#{Time.now.to_i}```
91
-
* create the database using ActiveRecord migrations
92
-
* load the contents from the dump file
93
-
* remove the dump file
94
-
95
-
Now your data is completely migrated and the library will now use ActiveRecord to handle anything database related :-)
79
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/change_master_password.rb -u you@example.com
96
80
97
81
### 1Password Conversion
98
82
···
102
86
Once you have created your initial user account through `bitwarden-ruby`, run
103
87
the conversion tool with your account e-mail address:
104
88
105
-
```
106
-
env RACK_ENV=production bundle exec ruby tools/1password_import.rb -f /path/to/data.1pif -u you@example.com
107
-
```
89
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/1password_import.rb -f /path/to/data.1pif -u you@example.com
108
90
109
91
It will prompt you for the master password you already created, and then
110
92
convert and import as many items as it can.
···
124
106
Once you have created your initial user account through `bitwarden-ruby`, run
125
107
the conversion tool with your account e-mail address:
126
108
127
-
```
128
-
env RACK_ENV=production bundle exec ruby tools/lastpass_import.rb -f /path/to/data.csv -u you@example.com
129
-
```
109
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/lastpass_import.rb -f /path/to/data.csv -u you@example.com
130
110
131
111
It will prompt you for the master password you already created, and then
132
112
convert and import as many items as it can.
···
145
125
Once you have created your initial user account through `bitwarden-ruby`, run
146
126
the conversion tool with your account e-mail address:
147
127
148
-
```
149
-
env RACK_ENV=production bundle exec ruby tools/bitwarden_import.rb -f /path/to/data.csv -u you@example.com
150
-
```
128
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/bitwarden_import.rb -f /path/to/data.csv -u you@example.com
151
129
152
130
It will prompt you for the master password you already created, and then
153
131
convert and import as many items as it can.
···
165
143
Once you have created your initial user account through `bitwarden-ruby`, run
166
144
the conversion tool with your account e-mail address:
167
145
168
-
```
169
-
env RACK_ENV=production bundle exec ruby tools/keepass_import.rb -f /path/to/data.kdbx -u you@example.com
170
-
```
146
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/keepass_import.rb -f /path/to/data.kdbx -u you@example.com
171
147
172
148
If your Keepass-database is secured using a keyfile, you can pass it using the `-k` parameter:
173
149
174
-
```
175
-
env RACK_ENV=production bundle exec ruby tools/keepass_import.rb -f /path/to/data.kdbx -k /path/to/keyfile.key -u you@example.com
176
-
```
150
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/keepass_import.rb -f /path/to/data.kdbx -k /path/to/keyfile.key -u you@example.com
177
151
178
152
It will prompt you for the master password you already created, and then
179
153
convert and import as many items as it can.
···
181
155
This tool operates on the SQLite database directly (not through its REST API)
182
156
so you can run it offline.
183
157
184
-
185
158
### 2-Factor Authentication
186
159
187
160
The Bitwarden browser extensions and mobile apps support accounts that require
···
190
163
signed up in the previous steps, run the `tools/activate_totp.rb` program on
191
164
the server:
192
165
193
-
env RACK_ENV=production bundle exec ruby tools/activate_totp.rb -u you@example.com
166
+
sudo -u _bitwarden env RACK_ENV=production bundle exec ruby tools/activate_totp.rb -u you@example.com
194
167
195
168
You'll be shown a `data:` URL that has a PNG-encoded QR code, which you must
196
169
copy and paste into a browser, then scan with your mobile TOTP authenticator
···
204
177
205
178
### License
206
179
207
-
Copyright (c) 2017 joshua stein `<jcs@jcs.org>`
180
+
Copyright (c) 2017-2018 joshua stein `<jcs@jcs.org>`
208
181
209
182
Permission to use, copy, modify, and distribute this software for any
210
183
purpose with or without fee is hereby granted, provided that the above
+1
-1
db/config.yml
+1
-1
db/config.yml