Skip to content

Commit a0c6899

Browse files
onuronur
committed
Merge branch 'doc' into web
2 parents 64b42f4 + 065a2f8 commit a0c6899

File tree

3 files changed

+204
-123
lines changed

3 files changed

+204
-123
lines changed

‎INSTALLATION.md

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# Installation Guide
2+
3+
## Requirements
4+
5+
`cratesfyi` is written in Rust and requires Rust compiler. It is developed under
6+
Linux, it may not work or compile under other operating systems. List of
7+
requirements to compile `cratesfyi`:
8+
9+
* rustc compiler
10+
* gcc
11+
* cmake
12+
* pkg-config
13+
* openssl (development files)
14+
* libmagic (development files)
15+
* git
16+
* postgresql
17+
* libc (development files)
18+
* lxc
19+
20+
## `cratesfyi-prefix` directory
21+
22+
`cratesfyi` is using a prefix directory for:
23+
24+
* Clone of `crates.io-index`
25+
* `documentations` directory to copy generated documentation
26+
* `sources` directory
27+
* `public_html` directory to serve some static files
28+
* `cratesfyi-container` a Linux container (LXC) to build crates in a safe
29+
environment
30+
31+
An example script to create cratesfyi-prefix directory (note: you don't need
32+
setup a lxc-container if you are gonna run only web interface,
33+
skip to setting up database):
34+
35+
36+
```sh
37+
#!/bin/sh
38+
# Creates cratesfyi-prefix directory for cratesfyi
39+
# This script is designed to run on Debian based operating systems,
40+
# and tested under Debian jessie and sid
41+
42+
set -e
43+
44+
PREFIX=$(pwd)/cratesfyi-prefix
45+
DIST_TEMPLATE=debian
46+
DIST_RELEASE=jessie
47+
DIST_MIRROR=http://httpredir.debian.org/debian
48+
49+
mkdir $PREFIX
50+
mkdir -p $PREFIX/sources $PREFIX/documentations
51+
git clone https://github.com/rust-lang/crates.io-index.git $PREFIX/crates.io-index
52+
53+
# Create debian8 lxc container into cratesfyi-container directory
54+
# Use your own distribution template and release name
55+
sudo LANG=C MIRROR=$DIST_MIRROR \
56+
lxc-create -n cratesfyi-container -P $PREFIX \
57+
-t $DIST_TEMPLATE -- -r $DIST_RELEASE
58+
59+
# Due to some bug in lxc-attach this container
60+
# must have a symbolic link in /var/lib/lxc
61+
sudo ln -s $PREFIX/cratesfyi-container /var/lib/lxc
62+
63+
# Container directory must be accessible by current user
64+
sudo chmod 755 $PREFIX/cratesfyi-container
65+
66+
# Setup lxc network
67+
echo 'USE_LXC_BRIDGE="true"
68+
LXC_BRIDGE="lxcbr0"
69+
LXC_ADDR="10.0.3.1"
70+
LXC_NETMASK="255.255.255.0"
71+
LXC_NETWORK="10.0.3.0/24"
72+
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"
73+
LXC_DHCP_MAX="253"
74+
LXC_DHCP_CONFILE=""
75+
LXC_DOMAIN=""' | sudo tee /etc/default/lxc-net
76+
77+
# Start network interface
78+
sudo service lxc-net restart
79+
80+
# Setup network for container
81+
sudo sed -i 's/lxc.network.type.*/lxc.network.type = veth\nlxc.network.link = lxcbr0/' \
82+
$PREFIX/cratesfyi-container/config
83+
84+
# Start lxc container
85+
sudo lxc-start -n cratesfyi-container
86+
87+
# Add user accounts into container
88+
# cratesfyi is using multiple user accounts to run cargo simultaneously
89+
for user in $(whoami) cratesfyi updater; do
90+
sudo lxc-attach -n cratesfyi-container -- \
91+
adduser --disabled-login --disabled-password --gecos "" $user
92+
done
93+
94+
# Install required packages for rust installation
95+
sudo lxc-attach -n cratesfyi-container -- apt-get update
96+
sudo lxc-attach -n cratesfyi-container -- apt-get install -y file git curl sudo ca-certificates
97+
98+
# Install rust nightly into container
99+
sudo lxc-attach -n cratesfyi-container -- \
100+
su - -c 'curl -sSf https://static.rust-lang.org/rustup.sh | sh -s -- --channel=nightly'
101+
```
102+
103+
104+
The last step is to install cratesfyi into the guest machine
105+
(or build in guest machine). If your host and guest
106+
operating system is same simply build cratesfyi in release mode and copy into
107+
`/usr/local/bin` directory of guest system:
108+
109+
```sh
110+
cargo build --release
111+
cp target/release/cratesfyi CRATESFYI_PREFIX_DIR/rootfs/usr/local/bin/
112+
```
113+
114+
cratesfyi is only using `lxd-attach` command with sudo. Make sure your user
115+
account can use this command without root password. Example `sudoers` entry:
116+
117+
```text
118+
cratesfyi ALL=(ALL) NOPASSWD: /usr/bin/lxc-attach
119+
```
120+
121+
### Setting up database
122+
123+
cratesfyi is using postgresql database to store crate and build
124+
information. You need to set up database before using chroot builder. To do
125+
this:
126+
127+
```text
128+
$ sudo su - postgres -c psql
129+
# First create a user
130+
postgres=# CREATE USER cratesfyi WITH PASSWORD 'password';
131+
postgres=# CREATE DATABASE cratesfyi OWNER cratesfyi;
132+
postgres=# \q
133+
# Initialize database with cratesfyi
134+
$ CRATESFYI_DATABASE_URL=postgresql://cratesfyi:password@localhost cratesfyi database init
135+
```
136+
137+
## Environment variables
138+
139+
`cratesfyi` is using various environment variables to run. Those are:
140+
141+
```sh
142+
HOME=/srv/cratesfyi
143+
PATH=/srv/cratesfyi/.cargo/bin:/usr/local/bin:/usr/bin:/bin
144+
CRATESFYI_PREFIX=/srv/cratesfyi/cratesfyi-prefix
145+
CRATESFYI_DATABASE_URL='postgresql://cratesfyi@localhost'
146+
CRATESFYI_GITHUB_USERNAME='USERNAME'
147+
CRATESFYI_GITHUB_ACCESSTOKEN='TOKEN'
148+
```
149+
150+
You can also specify `RUST_LOG=cratesfyi` to see all log messages. It will only
151+
show `INFO` or more leveled log messages without any `RUST_LOG` environment
152+
variable.
153+
154+
Example systemd service file for cratesfyi:
155+
156+
```text
157+
[Unit]
158+
Description=Cratesfyi daemon
159+
After=network.target postgresql.service
160+
161+
[Service]
162+
User=cratesfyi
163+
Group=cratesfyi
164+
Type=forking
165+
PIDFile=/srv/cratesfyi/cratesfyi-prefix/cratesfyi.pid
166+
EnvironmentFile=/srv/cratesfyi/env
167+
ExecStart=/bin/sh -c '/srv/cratesfyi/cratesfyi daemon > /srv/cratesfyi/cratesfyi-prefix/cratesfyi.log 2>&1'
168+
WorkingDirectory=/srv/cratesfyi
169+
170+
[Install]
171+
WantedBy=multi-user.target
172+
```

‎README.md

Lines changed: 30 additions & 123 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,46 @@
1-
2-
# docs.rs
1+
# Docs.rs
32

43
[![Build Status](https://secure.travis-ci.org/onur/docs.rs.svg?branch=master)](https://travis-ci.org/onur/docs.rs)
54
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/onur/docs.rs/master/LICENSE)
65

7-
Documentation host for the Rust Programming Language crates.
8-
9-
10-
## Installation
11-
12-
cratesfyi needs `cratesfyi-prefix` directory and a postgresql server to run.
13-
This directory must have:
14-
15-
* Clone of `crates.io-index` repository.
16-
* `sources` directory for crate sources.
17-
* `cratesfyi-container` lxc container for building crates. This container
18-
must use exact same operating system as host machine to avoid conflicts
19-
(or you can build cratesfyi in guest system).
20-
* `documentations` directory for crate documentations.
21-
22-
23-
An example script to create cratesfyi-prefix directory. Make sure you have
24-
`git` and `lxc` packages installed. **Run this script as a normal user**:
25-
26-
27-
```sh
28-
#!/bin/sh
29-
# Creates cratesfyi-prefix directory for cratesfyi
30-
# This script is designed to run on Debian based operating systems,
31-
# and tested under Debian jessie and sid
32-
33-
set -e
34-
35-
PREFIX=$(pwd)/cratesfyi-prefix
36-
DIST_TEMPLATE=debian
37-
DIST_RELEASE=jessie
38-
DIST_MIRROR=http://httpredir.debian.org/debian
39-
40-
mkdir $PREFIX
41-
mkdir -p $PREFIX/sources $PREFIX/documentations
42-
git clone https://github.com/rust-lang/crates.io-index.git $PREFIX/crates.io-index
43-
44-
# Create debian8 lxc container into cratesfyi-container directory
45-
# Use your own distribution template and release name
46-
sudo LANG=C MIRROR=$DIST_MIRROR \
47-
lxc-create -n cratesfyi-container -P $PREFIX \
48-
-t $DIST_TEMPLATE -- -r $DIST_RELEASE
49-
50-
# Due to some bug in lxc-attach this container
51-
# must have a symbolic link in /var/lib/lxc
52-
sudo ln -s $PREFIX/cratesfyi-container /var/lib/lxc
53-
54-
# Container directory must be accessible by current user
55-
sudo chmod 755 $PREFIX/cratesfyi-container
56-
57-
# Setup lxc network
58-
echo 'USE_LXC_BRIDGE="true"
59-
LXC_BRIDGE="lxcbr0"
60-
LXC_ADDR="10.0.3.1"
61-
LXC_NETMASK="255.255.255.0"
62-
LXC_NETWORK="10.0.3.0/24"
63-
LXC_DHCP_RANGE="10.0.3.2,10.0.3.254"
64-
LXC_DHCP_MAX="253"
65-
LXC_DHCP_CONFILE=""
66-
LXC_DOMAIN=""' | sudo tee /etc/default/lxc-net
67-
68-
# Start network interface
69-
sudo service lxc-net restart
70-
71-
# Setup network for container
72-
sudo sed -i 's/lxc.network.type.*/lxc.network.type = veth\nlxc.network.link = lxcbr0/' \
73-
$PREFIX/cratesfyi-container/config
74-
75-
# Start lxc container
76-
sudo lxc-start -n cratesfyi-container
77-
78-
# Add user accounts into container
79-
# cratesfyi is using multiple user accounts to run cargo simultaneously
80-
for user in $(whoami) cratesfyi updater; do
81-
sudo lxc-attach -n cratesfyi-container -- \
82-
adduser --disabled-login --disabled-password --gecos "" $user
83-
done
84-
85-
# Install required packages for rust installation
86-
sudo lxc-attach -n cratesfyi-container -- apt-get update
87-
sudo lxc-attach -n cratesfyi-container -- apt-get install -y file git curl sudo ca-certificates
88-
89-
# Install rust nightly into container
90-
sudo lxc-attach -n cratesfyi-container -- \
91-
su - -c 'curl -sSf https://static.rust-lang.org/rustup.sh | sh -s -- --channel=nightly'
92-
```
93-
94-
95-
The last step is to install cratesfyi into the guest machine
96-
(or build in guest machine). If your host and guest
97-
operating system is same simply build cratesfyi in release mode and copy into
98-
`/usr/local/bin` directory of guest system:
6+
Docs.rs (formerly cratesfyi) is an open source project to host documentation
7+
of crates for the Rust Programming Language.
998

100-
```sh
101-
cargo build --release
102-
cp target/release/cratesfyi CRATESFYI_PREFIX_DIR/rootfs/usr/local/bin/
103-
```
9+
Docs.rs automatically builds crates' documentation released on crates.io using
10+
the nightly release of the Rust compiler.
10411

105-
cratesfyi is only using `lxd-attach` command with sudo. Make sure your user
106-
account can use this command without root password. Example `sudoers` entry:
12+
The README of a crate is taken from the readme field defined in Cargo.toml.
13+
If a crate doesn't have this field, no README will be displayed.
10714

108-
```text
109-
yourusername ALL=(ALL) NOPASSWD: /usr/sbin/chroot
110-
```
15+
### Redirections
11116

17+
Docs.rs is using semver to parse URLs. You can use this feature to access
18+
crates' documentation easily. Example of URL redirections for `clap` crate:
11219

113-
### Setting up database
20+
| URL | Redirects to documentation of |
21+
|------------------------------|------------------------------------------------|
22+
| <https://docs.rs/clap> | Latest version of clap |
23+
| <https://docs.rs/clap/^2> | 2.* version |
24+
| <https://docs.rs/clap/^2.9> | 2.9.* version |
25+
| <https://docs.rs/clap/2.9.3> | 2.9.3 version (you don't need = unlike semver) |
11426

115-
cratesfyi is using postgresql database to store crate and build
116-
information. You need to set up database before using chroot builder. To do
117-
this:
27+
The crates.fyi domain will redirect to docs.rs, supporting all of the
28+
redirects discussed above
11829

119-
```sh
120-
$ sudo su - postgres -c psql
121-
# First create a user
122-
postgres=# CREATE USER cratesfyi WITH PASSWORD 'password';
123-
postgres=# CREATE DATABASE cratesfyi OWNER cratesfyi;
124-
postgres=# \q
125-
# Initialize database with cratesfyi
126-
CRATESFYI_DATABASE_URL=postgresql://cratesfyi:password@localhost ./cratesfyi database init
127-
```
30+
#### Contributors
12831

129-
Make sure to export `CRATESFYI_DATABASE_URL` environment variable before
130-
using cratesfyi.
32+
* [https://github.com/onur](Onur Aslan)
33+
* [https://github.com/frewsxcv](Corey Farwell)
34+
* [https://github.com/jonhoo](Jon Gjengset)
35+
* [https://github.com/mattyhall](Matthew Hall)
36+
* [https://github.com/GuillaumeGomez](Guillaume Gomez)
37+
* [https://github.com/Mark-Simulacrum](Mark Simulacrum)
13138

39+
#### Sponsors
13240

133-
## Environment variables
41+
Hosting generously provided by:
13442

135-
cratesfyi is using few environment variables:
43+
![Leaseweb](https://docs.rs/leaseweb.gif)
13644

137-
* `CRATESFYI_PREFIX` Prefix directory for cratesfyi
138-
* `CRATESFYI_DATABASE_URL` Postgresql database URL
139-
* `RUST_LOG` Set this to desired log level to get log messages
45+
If you are interested in sponsoring Docs.rs, please don't hesitate to
46+
contact us at TODO.

‎src/lib.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
//! [Docs.rs](https://docs.rs) (formerly cratesfyi) is an open source project to host
2+
//! documentation of crates for the Rust Programming Language.
13
24
#[macro_use]
35
extern crate log;

0 commit comments

Comments
 (0)