Skip to content
This repository was archived by the owner on Feb 27, 2020. It is now read-only.
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .guides/content/Building-your-own-Box-Part-6fae.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Building your own Codio Box Part is easy and you get the huge benefit that in any Codio project, you can simply type the following command to install an entire component in seconds.

```bash
parts install my_new_box_part
```

# Using this Codio Guide
This Guide explains how to develop and publish your own Box Parts. You can navigate between sections in one of two ways

- using the Table of Contents (opened and closed using the Hamburger icon in the header bar)
- using the navigation buttons in the bottom right of this window.
11 changes: 11 additions & 0 deletions .guides/content/Class-definition-279c.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Look at the code in the left panel. The first three lines need to be present in all Parts files.

```ruby
class MySQL < Package
```

The class definition is the first important line for you to edit. In the example code, `MySQL` is the class name you define. You should choose a name that is unique across all packages.

The package name should use Ruby conventions (CamelCase). This essentially means that the first letter of each word within your class name should be upper case.


9 changes: 9 additions & 0 deletions .guides/content/Compilation-7660.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Compilation is only required if your source contains source code rather than a binary package.

Once you have submitted a Pull Request and it has been accepted, then Codio will manually compile your source and upload a binary to the Codio binary store. This means that `parts install` will not run the compilation (or installation) steps, greatly speeding up the experience for the end user.

While you are the development phase, `parts install` will run the `compile` method in your `.rb` package definition file.

This step contains one or more `execute` statements that are responsible for compiling the component, should compilation be necessary.


11 changes: 11 additions & 0 deletions .guides/content/Dependencies-c08b.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
If your Box Part requires other Box Parts to be installed before your Part is installed then you specify it here.

- `depends_on` followed by a space delimited list of Box Parts

If you need to refer to this dependency in any of your package methods (most likely the compilation step) then you may find the following helper useful

```ruby
get_dependency("dependent_package_name").prefix_path
```

This will only work if the dependent package is defined with `depends_on`.
18 changes: 18 additions & 0 deletions .guides/content/Descriptions---Version-44b4.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
The following class properties are required by your Box Part

# name
Please note the following aspects of the name

- it must match the file name of your package
- it is the Box Parts package name `parts install packagename`
- it must be unique across all packages


# version
The version of the component that you are installing

# description
A brief description of the Box Part. Make it just long enough to be meaningful when displayed in the parts listing.

# category
A constant that associates this Box Part with a component category. [Click here](open_file lib/autoparts/category.rb) to view the `lib/autoparts/category.rb` file where these constants are defined.
5 changes: 5 additions & 0 deletions .guides/content/Dev-setup-script-96ba.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
Box Parts is installed on every Codio Box by default and is installed in the `~/.parts` folder. In order to run Box Parts from the `workspace` folder, which we have just loaded from your forked repo, we need to reconfigure the system slightly.

> **[CLICK HERE](open_terminal bash dev-setup.sh)** to run the reconfiguration script. You only need to do this once.

If you want to see the script, [click here](open_file dev-setup.sh)
36 changes: 36 additions & 0 deletions .guides/content/Development-Process-Overview-892b.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
A Box Part is simply a snippet of Ruby code. You do not have to be a Ruby Ninja to write a Box Part although it will obviously make it a little bit easier.

You will have already forked the Box Parts repo on GitHub and loaded it into Codio. The following steps describe the general development process

# Preparation
1. Create a new branch (Git is already fully installed) for your new Part.
1. Create a new ruby package file in `lib/autoparts/packages`. You may want to look at the existing ones as examples.

# Coding the package
1. Define the compilation process. If you are downloading a 64-bit binary from the source, then this is not required.
1. Define the Installation process. This copies files from the extracted archive (`~/.parts/tmp/package_name_version)` to its destination (`~/.parts/packages/package_name/version)`
1. Define an optional post installation process. This allows you to perform additional operations once the package is fully installed, such as sample database, default config files, special folder creation etc.
1. Define service `start`, `stop` and `running` methods. If your package runs as a service, then you will need to define these methods in order to start or stop the service.
1. Define message `tips` method. Allows you to define the message output to the terminal window once the installation process is successfully completed.
1. Define post `uninstall` and `purge` methods. Codio will remove your installed files automatically but the `post_uninstall` and `purge` methods allow you to control the removal process.

# Testing
Now your package file is completed, you should test it and ensure that all relevant Box Parts commands are working (install, uninstall, start, stop, purge, status). You should also ensure that your installed package runs as expected.

# Publishing
At this point, your new Box Part will only work on this Codio project and will not be findable in any other project.

In order to publish it, you will need to push the repo back to GitHub and send us a [pull request](https://help.github.com/articles/creating-a-pull-request).

# Codio Steps
Your new Box Part will be checked and approved by Codio.

We perform these checks as it us important to us that the quality of the Box Parts library is maintained at a high level and to examine them for potential security issues. Once approved,

1. We will compile your Box Part
1. We upload the binary to the Codio Box Parts binary store.
1. Merge your changes, at which point it will be available for all Codio users.

We do the above steps in order to avoid your Box Part needing to be compiled each time it is installed. This will significantly speed up the installation process.


1 change: 1 addition & 0 deletions .guides/content/Exporting-environment-variables-8d20.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
You can define environment variables as shown on the left.
19 changes: 19 additions & 0 deletions .guides/content/Figuring-out-the-directory-name-fd03.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
Before the compilation step, your source is downloaded from the specified URL and unpacked to a temporary location. That location will be the current working directory for the `compilation` and `installation` methods.

You may want to specify the directory name of the unpacked component. You will find code like this in a typical Parts package method

```bash
Dir.chdir('mysql-5.6.13') do
```

To figure out what the correct directory name is, the easiest thing to do is to download the component, then unpack it and review the folder structure.

```bash
cd ~
mkdir tmp
cd tmp
wget component_url
tar -zxvf component.tar.gz
ls -al
```

1 change: 1 addition & 0 deletions .guides/content/Installation-b4ba.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The installation step follows the compilation step, if there was one. This consists of one or more shell commands that perform the final installation step into `prefix_path`.
35 changes: 35 additions & 0 deletions .guides/content/Methods-915d.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
Box Parts provides several helper methods to let you reference paths, names, versions etc.

If you want to see all methods, please [click here](open_file lib/autoparts/package.rb).

When you install a package, your files will end up in the following folder structure

~/.parts/packages/package_name/version

# Package Methods
It is worth you being aware of the following methods

- **user** : the Codio user name
- **name_with_version** : package_name-version
- **extracted_archive_path** : path to the temporary folder where the downloaded archive was extracted
- **prefix_path** : destination folder for the installed package
- **etc_path** : the path to your `etc` folder
- **bin_path** :
- **sbin_path** :
- **include_path** :
- **lib_path** :
- **libexec_path** :
- **share_path** :

# Global Path Methods
You can also reference Box Parts system paths that are not a part of your package to store user related data. Anything placed in these paths will not be removed automatically when you run `parts uninstall`.

- **Path.bin**
- **Path.etc**
- **Path.lib**
- **Path.tmp**
- **Path.var**

To see all available Paths, [click here](open_file lib/autoparts/path.rb)


8 changes: 8 additions & 0 deletions .guides/content/Post-Installation-tasks-809f.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
The Post Installation step is called once the full installation is completed and carries out tasks such as installing a default database or modifying configuration files.

# Where to put your config files
Once your installation is complete,

- Configuration files should be placed in `Path.etc` (e.g. `~/.parts/etc`) or `Path.etc + name` (e.g. `~/.parts/etc/postgresql`).
- Data files (e.g. database files) should be placed in `Path.var + name` (e.g. `~/.parts/var/postgresql`).
- Log files should be placed in `Path.var + 'log' + "# {name}.log"` (e.g. `~/.parts/var/log/postgresql.log`)
2 changes: 2 additions & 0 deletions .guides/content/Post-installation-message-262d.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
If you want to display a message in the terminal window once your component has completed the installation then you can do so here.

10 changes: 10 additions & 0 deletions .guides/content/Services---start--stop---running-cf82.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
If your Part runs as a service, you will need to implement `start`, `stop` and `running` methods so your Part can be started and stopped from the command line using

```bash
parts start part_name
parts stop part_name
```

`running` is provided so the `parts status` command can check the status of your service.


34 changes: 34 additions & 0 deletions .guides/content/Source-5ad0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
This is where you specify the remote location of the component you want to install. It can be a binary or source code.

- `source_url` - the url of the component
- `source_sha1` '06e1d856cfb1f98844ef92af47d4f4f7036ef294'
- `source_filetype` - should be `tar.gz` or `zip`

# Understanding the process
When you run `parts install package_name` Codio checks whether the component (version specific) exists in the Codio binary store. If it exists, then it will be downloaded and installed (in the `~/.parts/packages/package_name/version`) without executing the Compilation or Installation steps (described in upcoming sections).

Your package will only be present in the binary store once we have approved your Pull request, as described in the 'Development Process Overview' section, and then uploaded your compiled binary to the Codio binary store.

During the development of your new Box Parts package, it will not be present in the Codio binary store and so `parts install package_name` will first run the Compilation step followed by the Installation step.


# Selecting a fixed version
It is advisable to specify a fixed version of a component rather than the latest build. If you select a latest build, the file will get updated and as such the SHA1 hash will change and your installation will fail.

Some components will provide a directory structure where specific versions are clearly listed. Other components may be available as Git `tags`, in which case you would select the tag in GitHub or any other platform and then look for the Download URL.

# SHA1 hash
If the component does not list the SHA1 hash for you then you will need to manually download the component and calculate the hash yourself.

You can do this as follows from the command line.

```bash
cd ~
mkdir tmp
cd tmp
wget component_url
sha1sum downloaded_filename
```

You will then be shown the SHA1 value, which you can copy and paste into your file.

9 changes: 9 additions & 0 deletions .guides/content/Uninstalling---Purging-7550.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
Box Parts allows a part to be uninstalled using `parts uninstall part_name` or `parts purge part_name`.

# Uninstall
The uninstallation is handled automatically by Box Parts and removes the entire package folder.

It will not remove any data outside the package folder. If you want to perform custom actions, define them in the `post_uninstall` method.

# Purge
The purge process allows you to remove any user data that is not removed by `parts uninstall`.
Loading