Cabler is a Ruby on Rails 6 Web application to document (network?) infrastructure.
It is a prototype/hack/WIP born out of the necessary to document findings while dealing with issues in a mid-size (>5 16-Port switches) network. While the use case is computer networks, the general setup is open enough to be used with other kinds of linked devices (e.g. water? Electricity?).
The own code is released under the AGPLv3+ and copyright 2020 Felix Wolfsteller.
Some german incubative discussion is found at https://meta-community.org/ (a German discourse forum for 'IT' people in intentional communities and like-minded).
Locations should help you understand where e.g. cables end or where devices can be found. Locations can be nested (a location can have a parent and multiple child locations, like a place can have some buildings which can have some rooms).
Devices like Switches, Converters or Patchpanels (agreed, this is not a typical "device"). These can have different "ports" (calles Slots). In the case of a Patchpanel or a simple converter, a Port should be used twice and the device should be marked as "connector" upon creation.
A Connection between a device and a location (or a device and a device or a location and a location), optionally with port assignment and name.
Find examplary data for tests in test/fixtures/locations.yml etc. You can seed your database with this data using rails db:fixtures:load. Note that this will also create a user (see password inside file).
Locations
- Basement
- Office
- Floor
Devices
- Switch TL-N1 in the Basement
- Switch TL-N2 in the Office
- Patchpanel P-B in the Basement
- Patchpanel P-O in the Office
- Router pfSense in the Basement
Links (Ports in brackets)
- Router (2) connected to Switch TL-N1 (1)
- Switch TL-N1 (2) connected to Patchpanel P-B (3)
- Patchpanel P-B (3) connected to Patchpanel P-O (7)
- Switch TL-N2 (1) connected to Patchpanel P-O (7)
- Switch TL-N1 (3) connected to Floor
+-----------------+location: basement+-----+
| router Switch Patchpanel|
| pfSense TL-N1 P-B |
| +---+ +---+ +---+ |
<----+ 1 | +---->+ 1 | | 1 | |
| | 2 +--+ | 2 +--+ | 2 | |
| | 3 | | 3 | +------>+ 3 +-----+----------+
| +---+ | 4 | | 4 | | |
| +--+ 5 | | 5 | | |
| | +---+ | 6 | | |
| | +---+ | |
| | | |
+--------------+---------------------------+ |
| |
| +-----+location: office+---+-+
v | Switch Patchpanel | |
+--+location: floor+--+ | TL-N2 P-O | |
| | | +---+ +---+ | |
+---------------------+ | | 1 | | 1 | | |
| | 2 +<---+ | 2 | | |
| | 3 | | | 3 | | |
| | 4 | +--+ 4 +<-----+ |
| +---+ +---+ |
| |
+----------------------------+
We are running a pretty default Ruby on Rails 6 stack, currently using Ruby 2.6.1 . That means you need have to have
- ruby installed (e.g. with rvm)
- sqlite3 or any other db engine installed
- graphviz installed (
sudo apt install graphvizin most cases) - the nodejs/yarn stuff installed
- clone this repository
- run
bundle - run
rails db:migrate - fire up server (in dev, e.g. with
rails sor if you yarn,yarn dev) - create a User manually:
# Fire up a rails console, and enter relevant User.create! data, exit with CTRL+D
$ rails c git:(master|✚15…
Running via Spring preloader in process 14058
Loading development environment (Rails 6.0.2.1)
2.6.1 :001 > User.create! email: 'my@ma.il', password: 'mypassword', password_confirmation: 'mypassword'
(2.3ms) SELECT sqlite_version(*)
(0.1ms) begin transaction
User Exists? (0.5ms) SELECT 1 AS one FROM "users" WHERE "users"."email" = ? LIMIT ? [["email", "my@ma.il"], ["LIMIT", 1]]
User Create (1.1ms) INSERT INTO "users" ("email", "encrypted_password", "created_at", "updated_at") VALUES (?, ?, ?, ?) [["email", "my@ma.il"], ["encrypted_password", "$2a$11$hofRgWkBnjiGO6wtzkQVL.O6Jr/19FHuq1NM76focTArHx9IWAWvy"], ["created_at", "2020-02-11 09:03:12.280375"], ["updated_at", "2020-02-11 09:03:12.280375"]]
(2.3ms) commit transaction
=> #<User id: 980190964, email: "my@ma.il", created_at: "2020-02-11 09:03:12", updated_at: "2020-02-11 09:03:12">
2.6.1 :002 >
$Database Follow the typical rails database configuration (config/database.yml).
E-Mail To allow password reset etc. via e-mail (only in production), set following environment variables.
HOST=yourhost.comm
APP_HOST=yourhost.commm # to generate absolute URLs in mails
SENDER_EMAIL="Cabler\ Your\ Community\ <cabler@yourhost.commm>"
SMTP_SERVER=yourhost.commm
SMTP_DOMAIN=yourhost.commm
SMTP_PORT=587
SMTP_PWD=9098asdjlker!
SMTP_USER=iaowur32oalksSee above for email settings
A Guardfile and the respective gems for livereloading are set up. That means if you want your browser window to automaticall trigger a rerender when you changed some files, you can run guard -g livereload (in a separate shell).
There are very few tests which can be run with rails t. Use rails test -f for fast-failing mode (abort after first test fail).
System-tests can be run with rails test:system.
To run tests automatically on filechange, run bundle exec guard -g test . For this to exclude system tests, all tests with the name "System" in it are skipped (kind of a guard-minitest bug).
Own code (mostly app/ and test/) is released under the AGPLv3+ (included as file LICENSE in this repository).
Contributions are very welcome. Copyright-transfer of modifications to Felix Wolfsteller is assumed.
For fun, some of the files include comments to be compliant with (FSFEs) reuse.
gem install mailcatcher && mailcatcher && xdg-open localhost:1080 to install,
start and open mailcatcher. Should work out of the box in development mode.
As we are dealing with models in the physical domain, following a resources based UI and API is fine (and Rails is meant to do that, allthough it is not thorrowly used in this project).
Prefer good old stable setup: no hard dependency on Javascript (only progressive enhancements), render on server side.
Use solid and stable standards and conventions if available.
- minimal
rails test - Could not use rails-erd succesfull with Rails 6 (voormedia/rails-erd#322).
annotategem
The gems emd and redcarpet help in rendering markdown. The CHANGELOG is exposed via a PageController . The changelog file is symlinked like this:
cd app/views/pages
ln -s ../../../CHANGELOG.md changelog.mdA trick is to use a markdown layout (to wrap the rendered HTML in a bulma .content) that renders the application layout. For that, an _application.html.haml layout was symlinked:
cd app/views/layouts
ln -s application.html.haml _application.html.haml- Ruby and Ruby on Rails
- bulma.io as CSS framework
- HAML for a saner way to produce HTML
- devise for authentication
- friendly_id for ... friendly ids
- svg-pan-zoom JS for interating with a SVG similar to a map
- many others ...
No explicit modeling of "Port"s (think of Ethernet-Switches), instead a very loose polymorphic Link model. To make up the disadvantages of that choice, implemented classes to deal with ""directed" connections (for analysis):
In commit #c1f38256350dfce601e8fd76e82efbbc95d3e134 Rails 6 shiny new webpacker asset pipeline mechanism (using webpack) was removed in favor of old stable sprockets. This makes deployment easier but engaged JavaScript development harder.
Using the name "Device" and the gem "Devise" ... :)
E.g. for version 0.1.0:\
- Adjust VERSION in
config/application.rb, - adjust CHANGELOG,
git commit -m '0.1.0',git tag -a '0.1.0' -m '0.1.0',git push && git push --tags.